Project Management API

Authentication

The Project Management API is authenticated with an account-level developer token. Create one at Account → API keys → Developer API tokens. Tokens start with the cdt_acc_ prefix and grant full access to projects owned by the user who created them. Treat them like passwords.

Project-scoped widget keys (cdt_…) are not accepted on these endpoints — they only authorise the public conversation and widget API.

curl https://api.conduet.ai/v1/projects \
  -H "Authorization: Bearer cdt_acc_..." \
  -H "Content-Type: application/json"

Base URL

All management endpoints are served under:

Projects

POST /v1/projects
Authorization: Bearer cdt_acc_...
Content-Type: application/json

{
  "name": "Support copilot"
}

PATCH /v1/projects/proj_abc123
{
  "workflows": [
    {
      "id": "wf_main",
      "name": "Main",
      "steps": [ /* WorkflowStep[] */ ],
      "connections": [ /* StepConnection[] */ ]
    }
  ]
}

Chat with an agent

Send messages to a project's agent over HTTP without going through the widget. This is the fastest way to script conversations, run automated evals, or embed an agent behind your own UI. If you omit versionId, the request is routed to the in-editor development version — no publish required.

POST /v1/projects/proj_abc123/chat
Authorization: Bearer cdt_acc_...
Content-Type: application/json

{
  "message": "How do I reset my password?",
  "userId": "user_42",        // optional — defaults to "api", used for session state
  "versionId": "development"  // optional — "development" | "production" | "staging" | "<versionId>"
}

curl -X POST https://api.conduet.ai/v1/projects/proj_abc123/chat \
  -H "Authorization: Bearer cdt_acc_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello","userId":"user_42"}'

The JSON response contains the agent's messages, any tool calls, updated session variables, and the execution trace. Subsequent calls with the same userId continue the same conversation — session state (memory, variables, step stack) is kept on the server.

curl -N -X POST https://api.conduet.ai/v1/projects/proj_abc123/chat/stream \
  -H "Authorization: Bearer cdt_acc_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello","userId":"user_42"}'

# → data: {"type":"message","content":"Hi! How can I help?"}
# → data: {"type":"tool_call",...}
# → data: [DONE]

Chat endpoints are rate-limited per projectId:userId. Check X-RateLimit-Remaining on the response headers. Over the limit you'll get a 429.

Versions & Publishing

Knowledge Base

Channel Deployments

Project API Keys

Project-scoped keys are used by the widget and public conversation API. Mint them for each project you deploy.

Transcripts & Analytics

Developer Tokens (self-service)

A developer token cannot mint new developer tokens (to contain the blast radius of a leak). These endpoints are only usable from an interactive dashboard session.

Errors

All errors return a JSON body with an error message and a machine-readable code. Common codes are BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, and CONFLICT.