Semarize
Start building

Quickstart

Semarize has two integration routes. Choose the one that fits your use case.

API

Direct programmatic access. Send conversations, get structured evaluation results back via REST.

MCP

Connect Semarize tools into MCP-compatible clients like Claude Desktop, Cursor, or custom agents.

API Quickstart

Get your API key, create a run, and receive structured evaluation results. Three steps.

Prerequisites

  • A Semarize workspace (sign up at app.semarize.com/signup)
  • An API key generated from your workspace dashboard
  • A Kit code - created in the Semarize app or provided by your team
1

Get your API key

Go to Integration → API in your workspace. Generate a key. Keys follow the format smz_live_*. Store it securely - you won't see the full key again.

Base URL: https://api.semarize.com
Authorization header
Authorization: Bearer smz_live_your_api_key_here
2

Create a run

Send a POST to /v1/runs with your Kit code and conversation input.

A

Async

Recommended

Returns 202 immediately. Poll for results. Best for production.

B

Sync

Blocks until completion. Returns 200 with results inline. Falls back to 202 on timeout.

cURL - async (default)
curl -X POST https://api.semarize.com/v1/runs \
-H "Authorization: Bearer smz_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"kit_code": "A1B2C3D4",
"input": {
"transcript": "Rep: What's driving the urgency?\\nProspect: We're losing 3 hours a week..."
}
}'
Response - 202 Accepted
{
"run_id": "run_8f3a...",
"status": "queued",
"run_type": "api"
}

For sync mode, add "mode": "sync" to the request body. See the API Reference for full details.

3

Get your results

Poll GET /v1/runs/:runId until status is succeeded. The output field contains your structured results.

cURL - poll for results
curl https://api.semarize.com/v1/runs/YOUR_RUN_ID \
-H "Authorization: Bearer smz_live_your_key"
Response - succeeded
{
"run_id": "run_8f3a...",
"status": "succeeded",
"duration_ms": 1200,
"output": {
"kit_code": "A1B2C3D4",
"bricks": {
"pain_is_specific": {
"value": 64,
"confidence": 0.95,
"reason": "Pain identified but not quantified",
"evidence": ["losing 3 hours a week"]
}
}
}
}
API Reference

MCP Quickstart

Connect an MCP-compatible client (Claude Desktop, Cursor, or a custom agent) to Semarize. MCP requests use JSON-RPC 2.0 over HTTP.

Prerequisites

  • A Semarize workspace
  • A machine agent created in Integration → MCP → Agents
  • Agent key and secret (shown once at creation)
  • Scopes and tool permissions assigned to the agent

MCP boundary

MCP supports draft composition and safe inspection only. Publishing bricks and kits is not available through MCP - publish remains human-governed in the Semarize app.

1

Create a machine agent

Go to Integration → MCP → Agents in the Semarize app. Create a new agent and assign it:

  • Scopes - which categories of tools it can access (e.g. bricks:read, kits:create_draft)
  • Tool permissions - which specific tools are allowed (e.g. bricks.list, kits.create_draft)

Save the agent_key and agent_secret. The secret is shown once and cannot be retrieved later.

2

Authenticate

Exchange your agent credentials for a short-lived access token.

cURL - authenticate
curl -X POST https://api.semarize.com/api/agents/authenticate \
-H "Content-Type: application/json" \
-d '{
"agent_key": "your_agent_key",
"agent_secret": "your_agent_secret"
}'
Response
{
"access_token": "smz_at_...",
"expires_at": "2026-03-09T12:15:00Z",
"workspace_id": "ws_...",
"scopes": ["bricks:read", "kits:read"]
}

Token lifetime

Access tokens expire after 15 minutes. Re-authenticate to get a new token. If your MCP client config shows a static bearer token, the token must be refreshed externally before it expires.

3

List available tools

Send a tools/list request to confirm your agent can see the tools it needs. Only tools the agent has both the scope and explicit permission for will appear.

cURL - tools/list
curl -X POST https://api.semarize.com/api/mcp \
-H "Authorization: Bearer smz_at_..." \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'

If you see your expected tools in the response, the connection is working. If the list is empty, check that your agent has the correct scopes and tool permissions in the Semarize app.

4

Call a tool

Use tools/call to execute a tool. This example lists bricks in your workspace.

cURL - tools/call
curl -X POST https://api.semarize.com/api/mcp \
-H "Authorization: Bearer smz_at_..." \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "bricks.list",
"arguments": { "limit": 5 }
}
}'

If you get a successful response with your bricks listed, MCP is working. You're ready to integrate.

Troubleshooting

401 UnauthorizedToken expired or missing. Re-authenticate to get a fresh token.
Empty tools/listAgent is missing scopes or tool permissions. Check Integration → MCP → Agents.
-32001 tool_forbiddenTool is not allowlisted for this agent. Add it in the agent’s tool permissions.
-32602 Invalid paramsCheck required fields and value constraints for the tool.
429 Rate limitedLimit is 60 requests/minute per agent. Wait for the Retry-After duration.
MCP Reference