Skip to main content
POST
/
api
/
idl
/
upload
Upload IDL
curl --request POST \
  --url https://api.example.com/api/idl/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "programId": "<string>",
  "idl": {},
  "description": "<string>",
  "cpiMd": "<string>",
  "isPublic": true
}
'
{
  "400": {},
  "401": {},
  "409": {},
  "429": {},
  "500": {},
  "project": {
    "project.id": "<string>",
    "project.name": "<string>",
    "project.slug": "<string>",
    "project.programId": "<string>",
    "project.isPublic": true
  },
  "idl": {
    "idl.versionId": "<string>",
    "idl.version": 123,
    "idl.programName": "<string>",
    "idl.instructionCount": 123,
    "idl.accountCount": 123,
    "idl.errorCount": 123,
    "idl.eventCount": 123
  },
  "validation": {
    "validation.warnings": [
      {}
    ]
  }
}

​
Overview

Uploads a new IDL (Interface Description Language) file and creates a project. This endpoint validates the IDL structure, checks for duplicates, and generates documentation automatically.

​
Authentication

This endpoint requires authentication. Include a valid bearer token in the Authorization header.

​
Rate Limiting

This endpoint is rate-limited to prevent abuse. Upload rate limits apply per user.

​
Request Body

​
name
string
required
Project name. Will be slugified for URLs (e.g., “My Project” becomes “my-project”).
​
programId
string
required
Solana program ID. Must be unique per user - attempting to upload an IDL for an existing program ID will return a 409 error.
​
idl
object
required
The IDL JSON object. Must conform to Anchor IDL structure. Maximum size: 10MB.
​
description
string
Optional project description.
​
cpiMd
string
Optional CPI (Cross-Program Invocation) documentation in Markdown format. Maximum size: 5MB.
​
isPublic
boolean
default:true
Whether the project should be publicly visible. Defaults to true.

​
Response

​
project
object
Created project information.
​
project.id
string
Unique project identifier.
​
project.name
string
Project name.
​
project.slug
string
URL-friendly project slug.
​
project.programId
string
Solana program ID.
​
project.isPublic
boolean
Public visibility status.
​
idl
object
IDL version and metadata.
​
idl.versionId
string
Version identifier.
​
idl.version
number
Version number (starts at 1).
​
idl.programName
string
Program name extracted from IDL.
​
idl.instructionCount
number
Number of instructions in the IDL.
​
idl.accountCount
number
Number of account types defined.
​
idl.errorCount
number
Number of custom errors defined.
​
idl.eventCount
number
Number of events defined.
​
validation
object
Validation results.
​
validation.warnings
array
Non-critical validation warnings.

​
Error Codes

​
400
Bad Request
Missing required fields: name, programId, or idl not provided.IDL size exceeded: IDL exceeds 10MB limit.CPI.md size exceeded: CPI.md exceeds 5MB limit.Invalid IDL structure: IDL validation failed. Response includes details and warnings fields.
​
401
Unauthorized
Missing or invalid authentication token.
​
409
Conflict
Project already exists for this program ID. Response includes existingProjectId.
​
429
Too Many Requests
Rate limit exceeded. Wait before retrying.
​
500
Internal Server Error
Server error during upload. Response includes error details.

​
Examples

curl -X POST https://api.orquestra.dev/api/idl/upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "name": "My Token Program",
    "description": "A custom SPL token implementation",
    "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "idl": {
      "version": "0.1.0",
      "name": "my_token_program",
      "instructions": [
        {
          "name": "initialize",
          "accounts": [
            {
              "name": "mint",
              "isMut": true,
              "isSigner": false
            },
            {
              "name": "authority",
              "isMut": false,
              "isSigner": true
            }
          ],
          "args": [
            {
              "name": "decimals",
              "type": "u8"
            }
          ]
        }
      ],
      "accounts": [],
      "types": [],
      "errors": [],
      "events": []
    },
    "isPublic": true
  }'

​
Success Response (201)

{
  "project": {
    "id": "abc123def456",
    "name": "My Token Program",
    "slug": "my-token-program",
    "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "isPublic": true
  },
  "idl": {
    "versionId": "xyz789uvw012",
    "version": 1,
    "programName": "my_token_program",
    "instructionCount": 1,
    "accountCount": 0,
    "errorCount": 0,
    "eventCount": 0
  },
  "validation": {
    "warnings": []
  }
}

​
Error Response (409 - Duplicate)

{
  "error": "Project already exists for this program ID",
  "existingProjectId": "existing123"
}

​
Error Response (400 - Invalid IDL)

{
  "error": "Invalid IDL structure",
  "details": [
    "Missing required field: version",
    "Instructions array cannot be empty"
  ],
  "warnings": [
    "Consider adding error definitions for better debugging"
  ]
}

​
Behavior Notes

  • The endpoint automatically generates documentation from the IDL and caches it for 7 days
  • IDL data is stored both in the database and KV cache for fast retrieval
  • A default socials entry is created for the project
  • The first version is always numbered as version 1
  • Project names are automatically slugified for URL-friendly identifiers
  • Duplicate program IDs per user are not allowed (returns 409)

Build docs developers (and LLMs) love

Get started for freeTalk to us