REST API

Programmatic access to a connic project with API keys for runs, retrieval, cost data, and deployments. Connectors run agents in response to events.

Overview

The connic REST API provides project access outside of the dashboard. It pulls run results into external monitoring, manages retrieval programmatically, and queries cost data for billing dashboards.

All API requests are authenticated with project-scoped API keys and rate-limited per project. The full endpoint reference includes request and response schemas plus example requests. Open API endpoints.

Authentication

API requests are authenticated using API keys. Each key is scoped to a single project and can only access endpoints within that project. Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer cnc_your_api_key

Create and manage API keys in Project Settings → API Keys & MCP Auth. Keys start with the cnc_ prefix and are shown only once when created. Store them securely.

API Key Permissions

Each API key has an environment scope and the same action-level project permissions shown in Team & Permissions. By default, it covers all current and future environments and every API-supported permission available to its owner. Select an environment subset or individual permissions to narrow access; either selection can be edited later.

Rate Limiting

API requests are rate-limited per project. All API keys belonging to the same project share the limit. When the limit is exceeded, the API responds with:

Contact the connic team for higher limits.

Quick Examples

curl https://api.connic.co/v1/projects/{project_id}/runs/{run_id} \
  -H "Authorization: Bearer cnc_your_api_key"

curl -X POST "https://api.connic.co/v1/projects/{project_id}/retrieval/text?environment_id={env_id}" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Document text goes here...",
    "namespace": "docs.api",
    "entry_id": "my-custom-id"
  }'

Connections

Connections are reusable credential sets that connectors reference, shared by the whole project. These endpoints need the connections.view, connections.create, connections.update, or connections.delete permission.

Secret fields are write-only and come back masked. Slack Connections can only be created in the dashboard.

Connector Failures on Activation

Activating a deployment applies the connectors it declares in connectors/*.yaml. If a connector change fails, POST /v1/projects/{project_id}/deployments/{deployment_id}/activate returns 409 with the failures in detail.connector_failures and activates nothing. Add ?force=true to activate anyway; the failing connectors keep their current state.

Error Responses

The API uses standard HTTP status codes. Most error responses include a JSON body with a detail field describing the issue; proxied retrieval errors use error instead.