API Reference

Overview

Constants exposes your tools through REST API, MCP, and Slack — all backed by the same execution engine and security model as the web UI.

All interfaces run tools in the same secure sandbox with the same credential handling, logging, and audit trail.

Every tool ships as an MCP App widget. Hosts that implement the MCP Apps extension (ChatGPT, Claude Desktop, VS Code Insiders, Goose, Postman, MCPJam) render the tool’s UI inline with the chat — same HTML bundle that runs on constants.io.

REST API (V1)

Authentication

All API requests require an API key in the Authorization header.

Getting Your API Key

Log in to constants.io
Click your profile icon in the sidebar
Select API Keys
Create a new key — choose scopes: mcp:read (list tools), mcp:execute (run tools)

Using Your Key

curl -X GET https://constants.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL

https://constants.io/api/v1

Idempotency (required for writes)

All write requests (POST, PUT, PATCH, DELETE) must include an Idempotency-Key header — a UUID v4 generated per logical attempt — so retries are safe by default:

curl -X POST https://constants.io/api/v1/run/my_tool \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 3f9b2c1a-6e4d-4b8e-9a7d-2f8c1e5b4a9d" \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

See Idempotency for the full contract (error semantics, 24-hour TTL, MCP/Slack behavior, client patterns).

Endpoints

Method	Endpoint	Scope	Description
`GET`	`/v1/tools`	`mcp:read`	List all available tools with schemas
`POST`	`/v1/run/:toolName`	`mcp:execute`	Execute a tool by name
`GET`	`/v1/skill/:toolName`	`mcp:read`	Get tool documentation (markdown)
`GET`	`/v1/skills/search`	—	Search available tools
`POST`	`/v1/upload`	—	Upload files for tool execution

Example: List Tools

curl -X GET https://constants.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  {
    "name": "process_csv_data_abc12345",
    "description": "Filter and transform CSV data by column values",
    "inputSchema": {
      "type": "object",
      "properties": {
        "filter_column": { "type": "string", "description": "Column name to filter on" },
        "filter_value": { "type": "string", "description": "Value to match" }
      },
      "required": ["filter_column"]
    },
    "outputSchema": {
      "properties": [
        { "name": "row_count", "type": "number", "description": "Rows in output" }
      ]
    },
    "fileFields": []
  }
]

Example: Execute a Tool

curl -X POST https://constants.io/api/v1/run/process_csv_data_abc12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_column": "status",
    "filter_value": "active"
  }'

For fast tools, you get the result directly:

{
  "status": "completed",
  "output": {
    "row_count": 1247
  },
  "runId": "run_xyz789",
  "toolUrl": "https://constants.io/tools/process-csv-data"
}

For longer-running tools, you receive a running status with a runId to check later:

{
  "status": "running",
  "runId": "run_xyz789",
  "toolUrl": "https://constants.io/tools/process-csv-data"
}

Example: Get Tool Documentation

curl -X GET https://constants.io/api/v1/skill/process_csv_data_abc12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns markdown documentation describing the tool’s purpose, inputs, outputs, and usage. Add ?format=json for a structured response with metadata.

MCP Integration

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

Connecting an Agent

Configure your AI agent or IDE to use the Constants MCP server:

{
  "mcpServers": {
    "constants": {
      "url": "https://constants.io/api/mcp",
      "apiKey": "YOUR_API_KEY"
    }
  }
}

Supported Methods

Method	Description
`initialize`	Returns server capabilities
`tools/list`	Discover available tools (owned + shared)
`tools/call`	Execute a tool with arguments
`ping`	Keep-alive

Tool Discovery

{
  "method": "tools/list",
  "params": {}
}

Returns all tools the API key owner has access to, each with a name, description, and input schema.

Executing a Tool

{
  "method": "tools/call",
  "params": {
    "name": "process_csv_data_abc12345",
    "arguments": {
      "filter_column": "status",
      "filter_value": "active"
    }
  }
}

Slack Bot

Installing

Go to your workspace settings in Constants
Click Connect Slack
Authorize the Constants bot for your Slack workspace

Using the Bot

Mention the bot in any channel or thread:

@Constants run the CSV processor with filter_column=status and filter_value=active

The bot acknowledges your request, determines the right tool, executes it, and posts the results — all within the Slack thread.

Thread Context

When mentioned in a thread, the bot reads recent messages for context, enabling multi-turn interactions:

User: @Constants what tools do I have for processing data?
Bot: You have these tools: CSV Processor, JSON Transformer...

User: run the CSV processor with the defaults
Bot: Running CSV Processor... ✅ Processed 1,247 rows

Error Handling

All interfaces return consistent error responses:

Code	Meaning
`200`	Success
`400`	Bad Request — Invalid parameters (includes missing/invalid `Idempotency-Key`)
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — Insufficient permissions
`404`	Not Found — Tool doesn’t exist
`409`	Conflict — duplicate credential name, or an `Idempotency-Key` request is still in flight
`422`	Unprocessable — Tool requires credentials not available, or `Idempotency-Key` reused with a different body
`429`	Too Many Requests — Rate limit exceeded
`500`	Server Error

API Key Scopes

Scope	Grants
`mcp:read`	List tools, view schemas, download documentation
`mcp:execute`	Execute tools via REST API and MCP

Keys are hashed before storage. Create multiple keys with different scopes and revoke them individually from the API Keys settings.

API Reference

Overview

REST API (V1)

Authentication

Getting Your API Key

Using Your Key

Base URL

Idempotency (required for writes)

Endpoints

Example: List Tools

Example: Execute a Tool

Example: Get Tool Documentation

MCP Integration

Connecting an Agent

Supported Methods

Tool Discovery

Executing a Tool

Slack Bot

Installing

Using the Bot

Thread Context

Error Handling

API Key Scopes

Need Help?

Join Discord

Contact Support

API Reference

Documentation Index

​Overview

​REST API (V1)

​Authentication

​Getting Your API Key

​Using Your Key

​Base URL

​Idempotency (required for writes)

​Endpoints

​Example: List Tools

​Example: Execute a Tool

​Example: Get Tool Documentation

​MCP Integration

​Connecting an Agent

​Supported Methods

​Tool Discovery

​Executing a Tool

​Slack Bot

​Installing

​Using the Bot

​Thread Context

​Error Handling

​API Key Scopes

​Need Help?

Join Discord

Contact Support

Overview

REST API (V1)

Authentication

Getting Your API Key

Using Your Key

Base URL

Idempotency (required for writes)

Endpoints

Example: List Tools

Example: Execute a Tool

Example: Get Tool Documentation

MCP Integration

Connecting an Agent

Supported Methods

Tool Discovery

Executing a Tool

Slack Bot

Installing

Using the Bot

Thread Context

Error Handling

API Key Scopes

Need Help?