Skip to main content

​
Base URL

The Orquestra API is available at: 
https://api.orquestra.dev
All API endpoints are accessed via HTTPS. The API follows REST principles and returns JSON responses.

​
API Routes Structure

The API is organized into the following route groups:
  • /auth/* - Authentication endpoints (GitHub OAuth, user sessions)
  • /api/* - Core API endpoints (projects, instructions, transactions)
  • /api/idl/* - IDL management (upload, update, versioning)
  • /health - Health check endpoint

​
Response Format

All API responses follow a consistent JSON structure:

​
Success Response

{
  "projectId": "abc123",
  "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "instructions": [...]
}

​
Error Response

{
  "error": "Project not found or not public",
  "code": "NOT_FOUND",
  "details": {
    "projectId": "invalid-id"
  }
}

​
Standard Error Codes

​
400
Bad Request
Invalid request parameters or malformed JSON
​
401
Unauthorized
Missing or invalid authentication credentials
​
403
Forbidden
Valid authentication but insufficient permissions
​
404
Not Found
Resource does not exist or is not accessible
​
409
Conflict
Resource already exists (e.g., duplicate project)
​
422
Validation Error
Request validation failed with detailed error messages
​
429
Too Many Requests
Rate limit exceeded. Check Retry-After header
​
500
Internal Server Error
Server error occurred. Contact support if persistent

​
Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per IP address.

​
Rate Limit Tiers

​
API Endpoints
/api/*
100 requests per minuteStandard rate limit for public API endpoints including project listing, instruction queries, and account information.
​
Authentication
/auth/*
20 requests per minuteStricter limit on authentication endpoints to prevent abuse.
​
IDL Upload
/api/idl/upload
10 requests per minuteLimited rate for IDL uploads to protect storage resources.
​
Transaction Build
/:projectId/instructions/:name/build
30 requests per minuteRate limit for transaction building endpoints that interact with Solana RPC.

​
Rate Limit Headers

All API responses include rate limit information in headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1678901234
​
X-RateLimit-Limit
integer
Maximum number of requests allowed in the current window
​
X-RateLimit-Remaining
integer
Number of requests remaining in the current window
​
X-RateLimit-Reset
integer
Unix timestamp when the rate limit window resets
When rate limited, the API returns a 429 Too Many Requests response: 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "retryAfter": 45
}
The Retry-After header indicates seconds to wait before retrying.

​
Public vs Private Projects

Projects in Orquestra can be either public or private:

​
Public Projects

  • Accessible to all users without authentication
  • Listed in public project directory (GET /api/projects)
  • IDL and instructions are publicly queryable
  • Documentation is publicly available
  • Transaction building is open to all

​
Private Projects

  • Only visible to the project owner
  • Require authentication (JWT token) to access
  • Not listed in public project directory
  • Useful for development or proprietary programs
  • Can be made public at any time by the owner

​
Access Control Example

Authenticated users see both public and their own private projects: 
# Without authentication - only public projects
curl https://api.orquestra.dev/api/projects

# With authentication - public + your private projects
curl https://api.orquestra.dev/api/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications:

​
Allowed Origins

  • https://orquestra.dev (production)
  • http://localhost:3000 (local development)
  • http://localhost:5173 (Vite dev server)

​
Allowed Headers

  • Content-Type
  • Authorization
  • X-API-Key

​
Allowed Methods

  • GET, POST, PUT, DELETE, OPTIONS

​
Credentials

Credentials (cookies, authorization headers) are supported for authenticated requests.

​
Network Selection

When building transactions, you can specify the Solana network:
​
network
string
default:"mainnet"
Solana network or custom RPC URL:
  • "mainnet" or "mainnet-beta" - Solana Mainnet
  • "devnet" - Solana Devnet
  • Custom RPC URL - e.g., "https://my-rpc.com"

​
Example

{
  "accounts": { ... },
  "args": { ... },
  "feePayer": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "network": "devnet"
}

​
Pagination

List endpoints support pagination with query parameters:
​
page
integer
default:"1"
Page number (1-indexed)
​
limit
integer
default:"20"
Items per page (max: 100)
​
search
string
Search query to filter results

​
Pagination Response

{
  "projects": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}
​
pagination.page
integer
Current page number
​
pagination.limit
integer
Items per page
​
pagination.total
integer
Total number of items across all pages
​
pagination.totalPages
integer
Total number of pages

​
Caching

The API implements intelligent caching for performance:
  • IDL data is cached in KV storage for 7 days
  • Documentation is cached for 7 days and regenerated when IDL updates
  • Public API responses are cached when appropriate
  • Cache is automatically invalidated on updates

​
Health Check

Check API availability: 
curl https://api.orquestra.dev/health
Response: 
{
  "status": "ok",
  "timestamp": "2024-03-15T10:30:00.000Z"
}

​
Next Steps

Authentication

Learn how to authenticate API requests with JWT tokens or API keys

Projects

Explore project management endpoints for organizing your Solana programs

Instructions

Build and execute Solana transactions with program instructions

Build docs developers (and LLMs) love

Get started for freeTalk to us