Create a spec

POST

/specs

POST

/specs

$ curl -X POST "https://api.postman.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

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

namestringOptional

The API specification's name.

typeenumOptional

The type of API specification.

idstringOptional

The specification's ID.

createdAtdatetimeOptional

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

updatedAtdatetimeOptional

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

createdByintegerOptional

The user ID of the user that created the file.

updatedByintegerOptional

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