cURL
curl --request GET \
--url 'https://api.scale.com/v2/schema?schema_id=69320cc6425a4bf55273a32b' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer live_...'import json
import requests
API_KEY = 'live_...'
SCHEMA_ID = '69320cc6425a4bf55273a32b'
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'])
print(f"Schema ID: {schema_metadata['id']}")
print(f"Schema Name: {schema_metadata['name']}")
print(f"Required fields: {json_schema.get('required', [])}")
else:
print(f"Error: {response.status_code}")
const API_KEY = 'live_...';
const SCHEMA_ID = '69320cc6425a4bf55273a32b';
async function getSchema(schemaId) {
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);
console.log('Schema ID:', schemaMetadata.id);
console.log('Schema Name:', schemaMetadata.name);
console.log('Required fields:', jsonSchema.required);
} else {
console.error('Error:', response.status);
}
}
getSchema(SCHEMA_ID);
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.scale.com/v2/schema"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scale.com/v2/schema")
.header("Authorization", "Bearer <token>")
.asString();{
"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}}}"
}
}{
"status_code": 400,
"error": "schema_id is required"
}{
"status_code": 404,
"error": "Schema not found"
}{
"status_code": 500,
"error": "An error has occurred."
}Deliveries
Get a Delivery JSON Schema
Retrieve a delivery JSON schema by its unique identifier. Delivery JSON schemas define the structure and validation rules for task responses.
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_...'import json
import requests
API_KEY = 'live_...'
SCHEMA_ID = '69320cc6425a4bf55273a32b'
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'])
print(f"Schema ID: {schema_metadata['id']}")
print(f"Schema Name: {schema_metadata['name']}")
print(f"Required fields: {json_schema.get('required', [])}")
else:
print(f"Error: {response.status_code}")
const API_KEY = 'live_...';
const SCHEMA_ID = '69320cc6425a4bf55273a32b';
async function getSchema(schemaId) {
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);
console.log('Schema ID:', schemaMetadata.id);
console.log('Schema Name:', schemaMetadata.name);
console.log('Required fields:', jsonSchema.required);
} else {
console.error('Error:', response.status);
}
}
getSchema(SCHEMA_ID);
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.scale.com/v2/schema"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scale.com/v2/schema")
.header("Authorization", "Bearer <token>")
.asString();{
"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}}}"
}
}{
"status_code": 400,
"error": "schema_id is required"
}{
"status_code": 404,
"error": "Schema not found"
}{
"status_code": 500,
"error": "An error has occurred."
}Authentication
Authentication
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 schemaname- Human-readable name of the schemacreatedBy/updatedBy- User IDs of creators/updaterscreatedAt/updatedAt- Timestampsjson- 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_idparameter - Malformed
schema_id(invalid MongoDB ObjectId format)
- Missing
- 404 Not Found: Schema with the specified ID does not exist
- 401 Unauthorized: Invalid or missing authentication token
Example Code
Retrieve a Schema by ID
Retrieve a Schema by ID
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:Validate Task Data Against Schema (Python)
Validate Task Data Against Schema (Python)
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:- Retrieve the delivery using
/v2/delivery - Extract the
schema_idfrom the delivery metadata - Fetch the full schema definition using
/v2/schema - 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
bearerAuthbasicAuth
Your API Key is the Bearer token. See the Authentication section to learn how to access your key.
Query Parameters
The unique MongoDB ObjectId of the delivery JSON schema.
Example:
"507f1f77bcf86cd799439011"
Response
Delivery JSON schema retrieved successfully.
The delivery JSON schema object
Show child attributes
Show child attributes

