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}}}"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.genai.scale.com/llms.txt

Use this file to discover all available pages before exploring further.

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