Skip to main content
The synth contracts command provides access to OpenAPI specifications for building Task Apps and integrating with Synth services.

​
Overview

OpenAPI contracts define the HTTP interface between your code and Synth’s optimization services. These contracts enable you to:
  • Build Task Apps in any language (Rust, Go, TypeScript, Zig, etc.)
  • Generate type-safe client/server code
  • Validate your implementation against the specification
  • Understand required endpoints and data structures

​
Commands

​
show

Display a contract’s contents in your terminal. 
synth contracts show <contract-name>
Example: 
# View the Task App contract
synth contracts show task-app
This prints the full YAML specification to stdout, which you can:
  • Read directly in your terminal
  • Pipe to a file: synth contracts show task-app > task_app.yaml
  • Use with other tools: synth contracts show task-app | yq

​
path

Get the file system path to a contract (useful for code generators). 
synth contracts path <contract-name>
Example: 
# Get the path to the Task App contract
synth contracts path task-app

# Use with openapi-generator
openapi-generator generate \
  -i $(synth contracts path task-app) \
  -g rust \
  -o ./generated

​
Available Contracts

​
task-app

The Task App contract defines the HTTP interface that Task Apps must implement for prompt optimization and reinforcement learning. Endpoints:
  • GET /health - Health check (unauthenticated)
  • POST /rollout - Execute a rollout with a specific prompt/policy
  • GET /task_info - Get task metadata and dataset information (optional)
Use cases:
  • Building Task Apps in non-Python languages
  • Generating type-safe bindings for your language
  • Understanding the request/response structure
  • Validating your Task App implementation
Learn more: Polyglot Task Apps Guide

​
Examples

​
Generate Rust Types

# Get the contract and generate Rust types
CONTRACT=$(synth contracts path task-app)
openapi-generator generate \
  -i "$CONTRACT" \
  -g rust \
  -o ./rust-types

# Use in your Cargo.toml
# [dependencies]
# task-app-types = { path = "./rust-types" }

​
Generate Go Types

# Get the contract and generate Go types
CONTRACT=$(synth contracts path task-app)
openapi-generator generate \
  -i "$CONTRACT" \
  -g go \
  -o ./go-types

# Use in your Go code
# import "yourmodule/go-types"

​
Generate TypeScript Types

# Get the contract and generate TypeScript types
CONTRACT=$(synth contracts path task-app)
openapi-generator generate \
  -i "$CONTRACT" \
  -g typescript-axios \
  -o ./ts-types

# Use in your package.json
# "dependencies": {
#   "task-app-types": "file:./ts-types"
# }

​
Validate Against the Contract

Use tools like openapi-validator to check if your implementation matches the contract: 
# Save the contract
synth contracts show task-app > task_app.yaml

# Validate your Task App's responses
# (example with specific validation tool)
openapi-validator validate \
  --spec task_app.yaml \
  --endpoint /rollout \
  --response response.json

​
Building Without Python

You can access contracts without installing the Python SDK:

​
Direct Download

# Download from GitHub
curl -O https://raw.githubusercontent.com/synth-laboratories/synth-ai/main/synth_ai/contracts/task_app.yaml

​
View in Browser

​
Contract Structure

Each contract includes:
  1. Type Definitions - Complete schemas for all request/response objects
  2. Endpoint Specifications - Paths, methods, and parameters
  3. Authentication Requirements - Which endpoints require API keys
  4. Behavioral Documentation - How to implement the logic (in descriptions)
  5. Example Payloads - Sample requests and responses
  6. Error Schemas - Proper error response formats

​
Integration Workflow

Here’s a typical workflow for building a Task App in a non-Python language:
  1. Get the contract: 
    synth contracts show task-app > task_app.yaml
  2. Generate types (optional): 
    openapi-generator generate -i task_app.yaml -g rust -o ./types
  3. Implement the endpoints:
    • Read the behavioral documentation in the contract
    • Implement /health, /rollout, and optionally /task_info
    • Use generated types for type safety
  4. Test locally: 
    # Start your Task App
./my-task-app

# Test with curl
curl http://localhost:8001/health
  5. Deploy and connect: 
    # Expose via tunnel
cloudflared tunnel --url http://localhost:8001

# Start optimization
curl -X POST https://api.usesynth.ai/api/prompt-learning/online/jobs \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -d '{"algorithm":"mipro","config_body":{"prompt_learning":{"task_app_url":"https://your-tunnel.com"}}}'

​
See Also

​
Common Issues

​
Contract Not Found

If you see an error like “Contract ‘xyz’ not found”, make sure you’re using the correct contract name: 
# Correct
synth contracts show task-app

# Incorrect
synth contracts show task_app  # Wrong: use hyphen, not underscore

​
Code Generator Fails

If openapi-generator fails, ensure:
  1. You have the generator installed: npm install -g @openapitools/openapi-generator-cli
  2. The contract file exists and is valid YAML
  3. You’re using a supported generator: openapi-generator list

​
Types Don’t Match Runtime

If generated types don’t match actual responses:
  1. Make sure you’re using the latest version of synth-ai
  2. Regenerate types: synth contracts show task-app > contract.yaml && openapi-generator generate ...
  3. Check if you’re using the correct version of the contract