Sign in
API Specification

Create API Specification

Pre-release Endpoint This endpoint is currently in beta and is subject to change.

Creates a specification (OpenAPI or AsyncAPI) for an API. Note: You can only have one specification for an API.

post/v3/apis/{apiId}/specifications

Request body

idstring uuid

The API specification identifier.

contentstring required

The raw content of your API specification, in json or yaml format (OpenAPI or AsyncAPI).

type'oas2' | 'oas3' | 'asyncapi'

The type of specification being stored. This allows us to render the specification correctly.

If this field is not set, it will be autodetected from content

created_atstring date-time

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time

An ISO-8601 timestamp representation of entity update date.

Example request

{
  "id": "7710d5c4-d902-410b-992f-18b814155b53",
  "content": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example API\",\"version\":\"1.0.0\"},\"paths\":{\"/example\":{\"get\":{\"summary\":\"Example endpoint\",\"responses\":{\"200\":{\"description\":\"Successful response\"}}}}}}",
  "type": "oas3",
  "created_at": "2022-11-04T20:10:06.927Z",
  "updated_at": "2022-11-04T20:10:06.927Z"
}

Response

API specification (OpenAPI or AsyncAPI)

idstring uuid required

The API specification identifier.

contentstring required

The raw content of your API specification, in json or yaml format (OpenAPI or AsyncAPI).

type'oas2' | 'oas3' | 'asyncapi' required

The type of specification being stored. This allows us to render the specification correctly.

If this field is not set, it will be autodetected from content

created_atstring date-time required

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity update date.

Example response

{
  "id": "7710d5c4-d902-410b-992f-18b814155b53",
  "content": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example API\",\"version\":\"1.0.0\"},\"paths\":{\"/example\":{\"get\":{\"summary\":\"Example endpoint\",\"responses\":{\"200\":{\"description\":\"Successful response\"}}}}}}",
  "type": "oas3",
  "created_at": "2022-11-04T20:10:06.927Z",
  "updated_at": "2022-11-04T20:10:06.927Z"
}

Changes