Skip to main content
PUT
/
api
/
idl
/
:projectId
Update IDL
curl --request PUT \
  --url https://api.example.com/api/idl/:projectId \
  --header 'Content-Type: application/json' \
  --data '
{
  "idl": {},
  "cpiMd": "<string>"
}
'
{
  "400": {},
  "401": {},
  "404": {},
  "500": {},
  "versionId": "<string>",
  "version": 123,
  "programName": "<string>",
  "instructionCount": 123,
  "warnings": [
    {}
  ]
}

​
Overview

Updates a project’s IDL by creating a new version. This endpoint validates the new IDL, increments the version number, and regenerates documentation. Previous versions are preserved and remain accessible.

​
Authentication

This endpoint requires authentication. You must be the project owner to update the IDL.

​
Path Parameters

​
projectId
string
required
The unique project identifier for the IDL to update.

​
Request Body

​
idl
object
required
The updated IDL JSON object. Must conform to Anchor IDL structure. Will be validated before creating a new version.
​
cpiMd
string
Optional updated CPI documentation in Markdown format. Maximum size: 5MB.

​
Response

​
versionId
string
Unique identifier for the newly created version.
​
version
number
Version number of the newly created version (auto-incremented).
​
programName
string
Program name extracted from the updated IDL.
​
instructionCount
number
Number of instructions in the updated IDL.
​
warnings
array
Non-critical validation warnings about the updated IDL.

​
Error Codes

​
400
Bad Request
Missing required field: idl not provided.Invalid IDL: IDL validation failed. Response includes details field with specific errors.
​
401
Unauthorized
Missing or invalid authentication token.
​
404
Not Found
Project not found or access denied. You must be the project owner to update.
​
500
Internal Server Error
Server error during update. Response includes error details.

​
Examples

curl -X PUT https://api.orquestra.dev/api/idl/abc123def456 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "idl": {
      "version": "0.2.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"
            }
          ]
        },
        {
          "name": "mint_tokens",
          "accounts": [
            {
              "name": "mint",
              "isMut": true,
              "isSigner": false
            },
            {
              "name": "destination",
              "isMut": true,
              "isSigner": false
            },
            {
              "name": "authority",
              "isMut": false,
              "isSigner": true
            }
          ],
          "args": [
            {
              "name": "amount",
              "type": "u64"
            }
          ]
        }
      ],
      "accounts": [],
      "types": [],
      "errors": [
        {
          "code": 6000,
          "name": "InsufficientFunds",
          "msg": "Insufficient funds for operation"
        }
      ],
      "events": []
    },
    "cpiMd": "# Updated CPI Documentation\n\nNew instructions added in v0.2.0..."
  }'

​
Success Response (200)

{
  "versionId": "new789xyz012",
  "version": 2,
  "programName": "my_token_program",
  "instructionCount": 2,
  "warnings": []
}

​
Error Response (400 - Invalid IDL)

{
  "error": "Invalid IDL",
  "details": [
    "Instruction 'mint_tokens' missing required field 'args'",
    "Error code 6000 conflicts with existing error definition"
  ]
}

​
Error Response (404 - Access Denied)

{
  "error": "Project not found or access denied"
}

​
Versioning Behavior

  • Each update creates a new version with an auto-incremented version number
  • Previous versions are preserved and remain accessible via the Retrieve IDL endpoint
  • Version numbers start at 1 and increment sequentially
  • The new version immediately becomes the “latest” version
  • Project’s updated_at timestamp is updated to reflect the change

​
Cache Updates

  • The KV cache is automatically updated with the new version
  • Both versioned cache key (idl:{projectId}:{version}) and latest cache key (idl:{projectId}:latest) are updated
  • Documentation cache is regenerated based on the new IDL
  • Cache entries have a 7-day TTL (time-to-live)

​
Documentation Regeneration

  • Documentation is automatically regenerated from the updated IDL
  • The full documentation is cached for fast retrieval
  • CPI documentation (if provided) is included in the regenerated docs
  • Documentation reflects all instructions, accounts, types, errors, and events from the new IDL version

​
Best Practices

  • Always increment the version field in your IDL to track changes
  • Include descriptive error definitions for better debugging
  • Update cpiMd documentation when adding new cross-program invocation patterns
  • Test IDL validation locally before updating production projects
  • Use semantic versioning conventions in your IDL version field (e.g., “0.2.0”, “1.0.0”)

Build docs developers (and LLMs) love

Get started for freeTalk to us