Upload OpenAPI Spec file

Upload OpenAPI Specification

Upload a user-provided OpenAPI specification for an application. This endpoint allows you to manually upload an OpenAPI spec file when automatic discovery is not available or when you want to provide your own specification.

Key Features:

• Accepts OpenAPI 3.x specifications in YAML or JSON format
• Validates the specification before upload
• Uses the application ID as the asset identifier (one OAS per application)
• Subsequent uploads to the same application will overwrite the previous version
• Uploaded specs can be retrieved using the Get OpenAPI Spec file endpoint

Request Body:

The request body should contain the raw OpenAPI specification content in YAML or JSON format.

Content-Type: text/plain or application/x-yaml

Example Request (YAML):

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success

Example Request (JSON):

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

Response:

On success, returns a 200 OK response with presigned upload URLs. The spec is stored as a hosted asset and can be retrieved using the application ID as the oasId in the Get OpenAPI Spec file endpoint.

Error Responses:

• 400 Bad Request - The OpenAPI specification is invalid. The response will include validation error details.
• 404 Not Found - The specified application does not exist.
• 403 Forbidden - You do not have permission to access this application.

Asset Naming:

The uploaded OAS file is stored with the application ID as its name, creating a 1:1 relationship between applications and uploaded specs. This means:

• Each application can have exactly one uploaded OAS file
• The oasId for retrieval is the same as the application ID
• Re-uploading to the same application replaces the previous version (no conflict errors)

Validation:

The endpoint validates the OpenAPI specification before upload:

• Checks for valid YAML/JSON syntax
• Verifies OpenAPI 3.x version format
• Validates required fields (openapi, info, paths)
• Returns detailed error messages if validation fails

Retrieving Uploaded Specs:

After uploading, you can retrieve the spec using:

1. Direct retrieval: GET /api/v1/oas/{orgId}/{appId} - Use the application ID as the oasId
2. List view: GET /api/v1/oas/{orgId}/list - The uploaded spec will appear in the organization's OAS list
3. Application mapping: The uploaded spec can be mapped to applications via the mapping endpoints

🧾 Audited This is recorded as ORGANIZATION_CONFIGURATION_MODIFIED User Activity.

Requires write:scan_config permission.