> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create/Update Schema > Upset draft version of a JSON schema. Creates a new schema if it doesn't exist. ## OpenAPI ````yaml POST /v1/{workspace}/schema/{schema_slug}/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /v1/{workspace}/schema/{schema_slug}/: post: summary: Create/Update Schema description: >- Upset draft version of a JSON schema. Creates a new schema if it doesn't exist. operationId: upsert-schema parameters: - in: path name: workspace required: true schema: type: string description: Workspace slug (staging, production, etc.) - in: path name: schema_slug required: true schema: type: string description: Unique identifier of the schema - in: query name: commit required: false schema: type: boolean default: false description: Set to true to commit the schema immediately after creation/update - in: query name: commit_message required: false schema: type: string description: Commit message describing the changes (required when commit=true) requestBody: required: true content: application/json: schema: type: object required: - name - json_schema properties: name: type: string description: Human-readable name of the schema example: Order Placed Event description: type: string nullable: true description: >- Description of the schema. Can be used to describe which action this schema is linked to. example: Schema for order placement action json_schema: type: object description: >- Structure of the workflow or event payload. Follows standard [json schema specification](https://json-schema.org/draft/2020-12/schema). You can link this schema to a workflow or event to validate their input payload in API response. Same schema can be linked to multiple workflows and events. example: type: object $schema: https://json-schema.org/draft/2020-12/schema required: - order_id - amount properties: order_id: type: string amount: type: string additionalProperties: true example: name: Order Placed Event description: Schema for order placement action json_schema: type: object $schema: https://json-schema.org/draft/2020-12/schema required: - order_id - amount properties: order_id: type: string amount: type: string additionalProperties: true responses: '200': description: Successfully retrieved schema object content: application/json: schema: type: object properties: slug: type: string description: Unique identifier for the schema example: new-order-placed name: type: string description: Human-readable name of the schema example: Order Placed Event description: type: string nullable: true description: Description of the schema example: Schema for order placement action status: type: string enum: - draft - live description: >- Status of returned schema. By default, draft version is returned. You can set `mode=live` to fetch the live schema. example: draft hash: type: string description: Git-like hash for version tracking example: 382b707d4b1f8999a1xxxxxxxx json_schema: type: object nullable: true description: JSON schema passed in the request body. created_at: type: string format: date-time description: When the schema was created example: '2025-08-27T09:30:57.945326Z' updated_at: type: string format: date-time description: When the schema was last updated example: '2025-08-29T15:37:37.650177Z' commit_result: type: object nullable: true description: >- Commit result when commit=true is passed in query parameter properties: is_committed: type: boolean description: Whether the schema was successfully committed example: false errors: type: array items: type: string description: List of errors if commit failed example: 'hash: no uncommitted changes found' example: is_committed: false errors: - 'hash: no uncommitted changes found' example: slug: new-order-placed name: Order Placed Event description: Schema for order placement action status: draft hash: 382b707d4b1f8999a1xxxxxxxx json_schema: type: object $schema: https://json-schema.org/draft/2020-12/schema required: - order_id - amount properties: order_id: type: string amount: type: string additionalProperties: true created_at: '2025-08-27T09:30:57.945326Z' updated_at: '2025-08-29T15:37:37.650177Z' commit_result: is_committed: false errors: - 'hash: no uncommitted changes found' '400': description: Invalid schema format content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 400 error_code: type: string description: Error code identifier. example: error type: type: string description: Error type example: ValidationError message: type: string description: Error message example: >- {"json_schema": ["Schema looks like JSON data, not a JSON Schema. Include keywords like '$schema', 'type', 'properties', or '$defs'."]} detail: type: object description: Detailed error information example: json_schema: - >- Schema looks like JSON data, not a JSON Schema. Include keywords like '$schema', 'type', 'properties', or '$defs'. example: code: 400 error_code: error type: ValidationError message: >- {"json_schema": ["Schema looks like JSON data, not a JSON Schema. Include keywords like '$schema', 'type', 'properties', or '$defs'."]} detail: json_schema: - >- Schema looks like JSON data, not a JSON Schema. Include keywords like '$schema', 'type', 'properties', or '$defs'. '401': $ref: '#/components/responses/AuthenticationError' description: AuthenticationFailed - Invalid service token. '404': description: Schema not found content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 404 error_code: type: string description: Error code identifier example: not_found type: type: string description: Error type example: NotFound message: type: string description: Error message example: workspace 'staging4' not found detail: type: string description: Detailed error information example: workspace 'staging4' not found example: code: 404 error_code: not_found type: NotFound message: workspace 'staging4' not found detail: workspace 'staging4' not found security: - ServiceTokenAuth: [] servers: - url: https://management-api.suprsend.com x-codeSamples: - lang: cURL label: Upsert Schema source: > curl -X POST "https://management-api.suprsend.com/v1/{workspace}/schema/{schema_slug}/?commit=true&commit_message=Initial%20schema%20creation" \ --header 'Authorization: ServiceToken ' \ --header 'Content-Type: application/json' \ --data '{ "name": "Order Placed Event", "description": "Schema for order placement action", "json_schema": { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": ["order_id", "amount"], "properties": { "order_id": { "type": "string" }, "amount": { "type": "string" } }, "additionalProperties": true } }' components: responses: AuthenticationError: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 401 error_code: authentication_failed type: AuthenticationFailed message: Invalid service token. detail: Invalid service token. schemas: ErrorResponse: type: object properties: code: type: integer description: HTTP status code error_code: type: string description: Specific error code identifier type: type: string description: Error type classification message: type: string description: Human-readable error message detail: type: string description: Additional error details securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ServiceTokenAuth: type: apiKey in: header name: ServiceToken description: >- You can get Service Token from [SuprSend dashboard -> Account Settings -> Service Tokens](https://app.suprsend.com/en/account-settings/service-tokens) section. ````