API Reference - Testship Development Server Endpoints

Overview

When you run testship start, a local Express server is started that serves both the interactive UI and several API endpoints. These endpoints provide access to your program’s IDL and project information.

Base URL

By default, the API is available at:

http://localhost:3000

If you specify a custom port, use that instead:

testship start --port 8080
# API available at: http://localhost:8080

Endpoints

GET /api/idl

Returns the Interface Definition Language (IDL) for your Anchor program.

Response:

{
  "version": "0.1.0",
  "name": "your_program",
  "instructions": [
    {
      "name": "initialize",
      "accounts": [
        {
          "name": "user",
          "isMut": true,
          "isSigner": true
        }
      ],
      "args": [
        {
          "name": "data",
          "type": "u64"
        }
      ]
    }
  ],
  "accounts": [...],
  "types": [...],
  "errors": [...]
}

Example:

const response = await fetch("http://localhost:3000/api/idl");
const idl = await response.json();
console.log(idl.name); // "your_program"

Status Codes:

Code	Description
`200`	Success - IDL returned
`500`	Error reading or parsing IDL file

GET /api/project

Returns basic information about the current Anchor project.

Response:

{
  "name": "your_program",
  "root": "/path/to/your/anchor/project"
}

Example:

const response = await fetch("http://localhost:3000/api/project");
const project = await response.json();
console.log(project.name); // "your_program"
console.log(project.root); // "/path/to/your/anchor/project"

Status Codes:

Code	Description
`200`	Success - Project info returned

CORS

The API server has CORS enabled, allowing requests from any origin. This is useful for development and testing purposes.

Static Files

The server also serves the TestShip UI as static files. Accessing the root URL (http://localhost:3000) will load the interactive testing interface.

Development Usage

These API endpoints are primarily used by the TestShip UI internally, but you can also use them for:

Custom Integrations: Build custom tools that interact with your Anchor program
Testing: Verify your IDL structure programmatically
Automation: Integrate with other development tools

Example: Fetching IDL in a Script

import fetch from "node-fetch";

async function getInstructions() {
  try {
    const response = await fetch("http://localhost:3000/api/idl");
    const idl = await response.json();

    console.log("Available instructions:");
    idl.instructions.forEach((ix) => {
      console.log(`- ${ix.name}`);
    });
  } catch (error) {
    console.error("Error fetching IDL:", error);
  }
}

getInstructions();

Security Note

WebSocket Support

Next Steps

Learn about the CLI Commands
Explore the Interactive UI
Check out Hot Reloading