Skip to main content

​
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

  1. Log in to constants.io
  2. Click your profile icon in the sidebar
  3. Select API Keys
  4. 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

MethodEndpointScopeDescription
GET/v1/toolsmcp:readList all available tools with schemas
POST/v1/run/:toolNamemcp:executeExecute a tool by name
GET/v1/skill/:toolNamemcp:readGet 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

MethodDescription
initializeReturns server capabilities
tools/listDiscover available tools (owned + shared)
tools/callExecute a tool with arguments
pingKeep-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

  1. Go to your workspace settings in Constants
  2. Click Connect Slack
  3. 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:
CodeMeaning
200Success
400Bad Request — Invalid parameters (includes missing/invalid Idempotency-Key)
401Unauthorized — Invalid or missing API key
403Forbidden — Insufficient permissions
404Not Found — Tool doesn’t exist
409Conflict — duplicate credential name, or an Idempotency-Key request is still in flight
422Unprocessable — Tool requires credentials not available, or Idempotency-Key reused with a different body
429Too Many Requests — Rate limit exceeded
500Server Error

​
API Key Scopes

ScopeGrants
mcp:readList tools, view schemas, download documentation
mcp:executeExecute 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.

​
Need Help?

Join Discord

Get help from the community

Contact Support

Reach out to our team