Skip to main content

​
Overview

Constants exposes tools through a REST API for programmatic access, automation, and integration into existing workflows.
The Constants API is available for all tools. No additional configuration required.

​
REST API

​
Authentication

All API requests require authentication using an API key.

​
Getting Your API Key

  1. Log in to constants.io
  2. Click your profile icon in the sidebar
  3. Select API Keys
  4. Create a new key for API access

​
Using Your Key

Include your API key in the Authorization header: 
curl -X GET https://api.constants.io/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Base URL

All API endpoints are available at: 
https://api.constants.io/v1

​
Tools Endpoints

MethodEndpointDescription
GET/toolsList all your Tools
GET/tools/:idGet a specific Tool
POST/toolsCreate a new Tool
PUT/tools/:idUpdate a Tool
DELETE/tools/:idDelete a Tool
POST/tools/:id/runExecute a Tool

​
Runs Endpoints

MethodEndpointDescription
GET/tools/:id/runsList runs for a Tool
GET/runs/:idGet a specific run
GET/runs/:id/logsGet run logs
GET/runs/:id/artifactsList run artifacts
GET/artifacts/:idDownload an artifact

​
Example: Execute a Tool

curl -X POST https://api.constants.io/v1/tools/tool_abc123/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "filter_column": "status",
      "filter_value": "active"
    }
  }'
Response: 
{
  "run_id": "run_xyz789",
  "status": "running",
  "created_at": "2025-01-20T08:15:00Z",
  "tool": {
    "id": "tool_abc123",
    "name": "Process CSV Data",
    "version": "a1b2c3d4"
  }
}

​
Example: Get Run Status

curl -X GET https://api.constants.io/v1/runs/run_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "run_id": "run_xyz789",
  "status": "completed",
  "started_at": "2025-01-20T08:15:00Z",
  "completed_at": "2025-01-20T08:15:32Z",
  "duration_ms": 32000,
  "inputs": {
    "filter_column": "status",
    "filter_value": "active"
  },
  "outputs": {
    "row_count": 1247
  },
  "artifacts": [
    {
      "id": "art_123",
      "name": "filtered_output.csv",
      "size_bytes": 45230,
      "content_type": "text/csv"
    }
  ]
}

​
Rate Limits

To ensure fair usage, the API has rate limits:
TierRequests per minuteRuns per day
Free60100
Pro3001,000
EnterpriseCustomCustom
When you exceed rate limits, the API returns a 429 Too Many Requests response with a Retry-After header.

​
Error Handling

The API uses standard HTTP status codes:
CodeMeaning
200Success
201Created
400Bad Request — Invalid parameters
401Unauthorized — Invalid or missing API key
403Forbidden — Insufficient permissions
404Not Found — Resource doesn’t exist
429Too Many Requests — Rate limit exceeded
500Server Error — Something went wrong
Error responses include a JSON body with details: 
{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'tool_id' parameter is required",
    "param": "tool_id"
  }
}

​
Webhooks

Configure webhooks to receive notifications when events occur:
  • run.started — A Tool run has begun
  • run.completed — A Tool run finished successfully
  • run.failed — A Tool run failed
  • tool.updated — A Tool’s spec or version changed
Webhook configuration is available in your account settings.

​
SDKs

Official SDKs are coming soon for:
  • Python — pip install constants-sdk
  • JavaScript/TypeScript — npm install @constants/sdk
In the meantime, you can use any HTTP client to interact with the API.

​
Advanced: MCP Integration

For AI agent workflows, Constants also supports the Model Context Protocol (MCP) — a standard for AI agents to discover and execute tools.

​
Connecting an Agent

To connect an AI agent to your Constants tools:
  1. Get your API key from your account settings
  2. Configure your agent to use the Constants MCP server
{
  "mcpServers": {
    "constants": {
      "url": "https://api.constants.io/mcp",
      "apiKey": "YOUR_API_KEY"
    }
  }
}

​
Tool Discovery

Agents can discover available tools:
{
  "method": "tools/list",
  "params": {}
}

​
Executing a Tool

{
  "method": "tools/call",
  "params": {
    "name": "process-csv-data",
    "arguments": {
      "file": "base64-encoded-content",
      "filter_column": "status",
      "filter_value": "active"
    }
  }
}
MCP provides the same governance and auditability as the REST API.

​
Need Help?

Join Discord

Get help from the community

Contact Support

Reach out to our team