Create a spec file

POST

/specs/:specId/files

POST

/specs/:specId/files

$ curl -X POST https://api.getpostman.com/specs/73e15000-bc7a-4802-b80e-05fff18fd7f8/files \
>      -H "x-api-key: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "path": "schemas.json",
>   "content": "{\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\": \"#/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}"
> }'

1 {
2   "createdAt": "2025-07-22T19:29:08.000Z",
3   "createdBy": 12345678,
4   "id": "2fdc8ea1-d02e-4e50-989e-6fa28f42b995",
5   "path": "schemas.json",
6   "updatedAt": "2025-07-22T19:29:57.000Z",
7   "updatedBy": 12345678,
8   "type": "ROOT"
9 }

Creates a file for an OpenAPI or a protobuf 2 or 3 specification.

Note:

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.
Creating a spec file assigns it the DEFAULT file type.
Multi-file specifications can only have one root file.
Files cannot exceed a maximum of 10 MB in size.

Creates a file for an OpenAPI or a protobuf 2 or 3 specification. **Note:** - 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. - Creating a spec file assigns it the `DEFAULT` file type. - Multi-file specifications can only have one root file. - Files cannot exceed a maximum of 10 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)>.

Path parameters

specIdstringRequired

The spec's ID.

Request

Create Spec File

pathstringRequired

The file's path. Accepts JSON or YAML files.

contentstringRequired

The file's stringified contents.

Response

Successful Response

createdAtdatetime

The date and time at which the file was created.

createdByinteger

The user ID of the user that created the file.

idstring

The file's ID.

pathstring

The file's path.

updatedAtdatetime

The date and time at which the file was updated.

updatedByinteger

The ID of the user who updated the file.

typeenumDefaults to DEFAULT

The type of file:

ROOT — The file containing the full OpenAPI structure. This serves as the entry point for the API spec and references other (DEFAULT) spec files. Multi-file specs can only have one root file.
DEFAULT — A file referenced by the ROOT file.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error