Skip to main content
GET
/
v2
/
schema
cURL
curl --request GET \
  --url 'https://api.scale.com/v2/schema?schema_id=69320cc6425a4bf55273a32b' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer live_...'
{
  "schema": {
    "id": "69320cc6425a4bf55273a32b",
    "name": "[FDE] 69310af9143320c1b09c60bb",
    "createdBy": "68a3b49f35187612f3a28630",
    "createdAt": "2025-12-04T22:35:50.549Z",
    "updatedBy": "68a3b49f35187612f3a28630",
    "updatedAt": "2025-12-04T22:36:34.221Z",
    "json": "{\"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"type\": \"object\", \"required\": [\"task_id\", \"project\", \"status\"], \"properties\": {\"task_id\": {\"type\": \"string\", \"minLength\": 1}, \"project\": {\"type\": \"string\", \"minLength\": 1}, \"status\": {\"type\": \"string\", \"minLength\": 1}}}"
  }
}
Every request sent to Scale’s API requires authentication. In short, your API Key is the Bearer token. See the Authentication section for more details.

​
Required query parameters

You must provide:
  • schema_id - Schema IDs are globally unique and used to validate delivery data structures.

​
Overview

Retrieves a delivery JSON schema by its unique identifier. Delivery JSON schemas define the structure and validation rules for task responses in customer applications.

​
Use Cases

  • Validate delivery data: Ensure your delivery data conforms to the expected structure
  • Data integration: Understand the structure of delivery data for integration purposes

​
Response

Returns a JSON object containing the complete schema definition including:
  • id - Unique MongoDB ObjectId identifier for the schema
  • name - Human-readable name of the schema
  • createdBy / updatedBy - User IDs of creators/updaters
  • createdAt / updatedAt - Timestamps
  • json - Stringified JSON Schema definition containing validation rules and structure
The json field contains a stringified JSON Schema that needs to be parsed before use. Parse it with JSON.parse() in JavaScript or json.loads() in Python.

​
Error Responses

  • 400 Bad Request:
    • Missing schema_id parameter
    • Malformed schema_id (invalid MongoDB ObjectId format)
  • 404 Not Found: Schema with the specified ID does not exist
  • 401 Unauthorized: Invalid or missing authentication token

​
Example Code

import json
import requests

API_KEY = 'live_...'
SCHEMA_ID = '69320cc6425a4bf55273a32b'

def get_schema(schema_id: str):
    response = requests.get(
        url="https://api.scale.com/v2/schema",
        params={"schema_id": schema_id},
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_KEY}",
        },
    )

    if response.status_code == 200:
        data = response.json()
        schema_metadata = data['schema']

        # Parse the JSON Schema string
        json_schema = json.loads(schema_metadata['json'])

        return schema_metadata, json_schema
    else:
        print(f"Error: {response.status_code}")
        print(response.json())
        return None, None

if __name__ == "__main__":
    metadata, json_schema = get_schema(SCHEMA_ID)
    if metadata:
        print(f"Schema ID: {metadata['id']}")
        print(f"Schema Name: {metadata['name']}")
        print(f"Created At: {metadata['createdAt']}")
        print(f"\nRequired fields: {json_schema.get('required', [])}")
        print(f"Properties: {list(json_schema.get('properties', {}).keys())}")

const API_KEY = 'live_...';
const SCHEMA_ID = '69320cc6425a4bf55273a32b';

async function getSchema(schemaId) {
  try {
    const response = await fetch(
      `https://api.scale.com/v2/schema?schema_id=${schemaId}`,
      {
        method: 'GET',
        headers: {
          'Accept': 'application/json',
          'Authorization': `Bearer ${API_KEY}`,
        },
      }
    );

    if (response.ok) {
      const data = await response.json();
      const schemaMetadata = data.schema;

      // Parse the JSON Schema string
      const jsonSchema = JSON.parse(schemaMetadata.json);

      return { metadata: schemaMetadata, jsonSchema };
    } else {
      const error = await response.json();
      console.error(`Error: ${response.status}`, error);
      return null;
    }
  } catch (error) {
    console.error('Request failed:', error);
    return null;
  }
}

// Usage
getSchema(SCHEMA_ID).then(result => {
  if (result) {
    const { metadata, jsonSchema } = result;
    console.log('Schema ID:', metadata.id);
    console.log('Schema Name:', metadata.name);
    console.log('Created At:', metadata.createdAt);
    console.log('\nRequired fields:', jsonSchema.required);
    console.log('Properties:', Object.keys(jsonSchema.properties));
  }
});

curl --request GET \
  --url 'https://api.scale.com/v2/schema?schema_id=69320cc6425a4bf55273a32b' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer live_...'

​
Validating Data with the Schema

Once you retrieve a schema, you can use it to validate task data: 
import json
import requests
from jsonschema import validate, ValidationError

API_KEY = 'live_...'
SCHEMA_ID = '69320cc6425a4bf55273a32b'

# Get the schema
response = requests.get(
    url="https://api.scale.com/v2/schema",
    params={"schema_id": SCHEMA_ID},
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
)

schema_metadata = response.json()['schema']
json_schema = json.loads(schema_metadata['json'])

# Example task data to validate
task_data = {
    "task_id": "task_123",
    "project": "my_project",
    "status": "completed",
    "created_at": "2025-01-13T10:00:00Z",
    "batch": "batch_456",
    "prompt_audio_url": "https://example.com/audio.mp3",
    "natural_response_url": "https://example.com/response.mp3",
    "natural_response_transcript": "Hello world",
    "response_reading_url": "https://example.com/reading.mp3",
    "metadata": {}
}

# Validate the data
try:
    validate(instance=task_data, schema=json_schema)
    print("✓ Task data is valid!")
except ValidationError as e:
    print(f"✗ Validation failed: {e.message}")

​
Integration with Deliveries

Schemas are referenced in delivery objects and can be used to validate the structure of task responses. When working with deliveries, you can:
  1. Retrieve the delivery using /v2/delivery
  2. Extract the schema_id from the delivery metadata
  3. Fetch the full schema definition using /v2/schema
  4. Validate task responses against the schema
Schema IDs are immutable once created. If you need to modify a schema, you must create a new schema version with a new ID.

Authorizations

​
Authorization
string
header
required

Your API Key is the Bearer token. See the Authentication section to learn how to access your key.

Query Parameters

​
schema_id
string
required

The unique MongoDB ObjectId of the delivery JSON schema.

Example:

"507f1f77bcf86cd799439011"

Response

Delivery JSON schema retrieved successfully.

​
schema
object
required

The delivery JSON schema object