Create a spec

POST

/specs

POST

/specs

$ curl -X POST "https://api.getpostman.com/specs?workspaceId=1f0df51a-8658-4ee8-a2a1-d2567dfa09a9" \
>      -H "x-api-key: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "name": "Sample API",
>   "type": "OPENAPI:3.0",
>   "files": [
>     {
>       "content": "{\n  \"openapi\": \"3.0.0\",\n  \"info\": {\n    \"version\": \"1.0.0\",\n    \"title\": \"Sample API\",\n    \"description\": \"Buy or rent spacecrafts\"\n  },\n  \"paths\": {\n    \"/spacecrafts/{spacecraftId}\": {\n      \"parameters\": [\n        {\n          \"name\": \"spacecraftId\",\n          \"description\": \"The unique identifier of the spacecraft\",\n          \"in\": \"path\",\n          \"required\": true,\n          \"schema\": {\n            \"$ref\": \"#/components/schemas/SpacecraftId\"\n          }\n        }\n      ],\n      \"get\": {\n        \"summary\": \"Read a spacecraft\",\n        \"responses\": {\n          \"200\": {\n            \"description\": \"The spacecraft corresponding to the provided `spacecraftId`\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"$ref\": \"#/components/schemas/Spacecraft\"\n                }\n              }\n            }\n          },\n          \"404\": {\n            \"description\": \"No spacecraft found for the provided `spacecraftId`\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"$ref\": \"#/components/schemas/Error\"\n                }\n              }\n            }\n          },\n          \"500\": {\n            \"description\": \"Unexpected error\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"$ref\": \"#/components/schemas/Error\"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  \"components\": {\n    \"schemas\": {\n      \"SpacecraftId\": {\n        \"description\": \"The unique identifier of a spacecraft\",\n        \"type\": \"string\"\n      },\n      \"Spacecraft\": {\n        \"type\": \"object\",\n        \"required\": [\n          \"id\",\n          \"name\",\n          \"type\"\n        ],\n        \"properties\": {\n          \"id\": {\n            \"$ref\": \"#/components/schemas/SpacecraftId\"\n          },\n          \"name\": {\n            \"type\": \"string\"\n          },\n          \"type\": {\n            \"type\": \"string\",\n            \"enum\": [\n              \"capsule\",\n              \"probe\",\n              \"satellite\",\n              \"spaceplane\",\n              \"station\"\n            ]\n          },\n          \"description\": {\n            \"type\": \"string\"\n          }\n        }\n      },\n      \"Error\": {\n        \"type\": \"object\",\n        \"required\": [\n          \"message\"\n        ],\n        \"properties\": {\n          \"message\": {\n            \"description\": \"A human readable error message\",\n            \"type\": \"string\"\n          }\n        }\n      }\n    },\n    \"securitySchemes\": {\n      \"ApiKey\": {\n        \"type\": \"apiKey\",\n        \"in\": \"header\",\n        \"name\": \"X-Api-Key\"\n      }\n    }\n  },\n  \"security\": [\n    {\n      \"ApiKey\": [\n\n      ]\n    }\n  ]\n}",
>       "path": "index.json",
>       "type": "DEFAULT"
>     }
>   ]
> }'

1 {
2   "name": "Sample API",
3   "type": "OPENAPI:3.0",
4   "id": "b4fc1bdc-6587-4f9b-95c9-f768146089b4",
5   "createdAt": "2025-03-15T13:48:28.000Z",
6   "updatedAt": "2025-03-15T13:48:28.000Z",
7   "createdBy": 12345678,
8   "updatedBy": 12345678
9 }

Creates an API specification in Postman’s Spec Hub. Specifications can be single or multi-file.

Note:

Postman supports OpenAPI (2.0, 3.0, and 3.1), AsyncAPI (2.0 and 3.0), protobuf (2 and 3), GraphQL, and Smithy specifications.
If the file path contains a / (forward slash) character, then a folder is created. For example, if the path is the components/schemas.json value, then a components folder is created with the schemas.json file inside.
Multi-file specifications can only have one root file.
Files cannot exceed a maximum of 12 MB in size.

Creates an API specification in Postman's [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/). Specifications can be single or multi-file. **Note:** - Postman supports OpenAPI (2.0, 3.0, and 3.1), AsyncAPI (2.0 and 3.0), protobuf (2 and 3), GraphQL, and Smithy specifications. - If the file path contains a `/` (forward slash) character, then a folder is created. For example, if the path is the `components/schemas.json` value, then a `components` folder is created with the `schemas.json` file inside. - Multi-file specifications can only have one root file. - Files cannot exceed a maximum of 12 MB in size.

Authentication

x-api-keystring

API Key authentication via header

Authorizationstring

A valid SCIM API key for calls to SCIM endpoints.

A valid [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key) for calls to SCIM endpoints.

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Query parameters

workspaceIdstringRequired

The workspace's ID.

Request

This endpoint expects an object.

namestringRequired

The specification's name.

typeenumRequired

The type of API specification.

fileslist of objectsRequired

A list of the specification's files and their contents.

Response

Created

namestring

The API specification's name.

typeenum

The type of API specification.

idstring

The specification's ID.

createdAtdatetime

The date and time at which the specification file was created.

updatedAtdatetime

The date and time at which the file was last updated.

createdByinteger

The user ID of the user that created the file.

updatedByinteger

The user ID of the user that last updated the specification file.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error