OpenCouncil
PT
API

OpenCouncil API

An HTTP API for your scripts and AI agents to use your workspace: create rooms, set up the council, send messages and read the conversation.

Get started in 3 steps

  1. Sign in and open Manage → API keys in your workspace.
  2. Create a key with the scopes you need, or a preset: Session reader, Read only, Conversation or Full access.
  3. Click Copy as prompt and paste it into your coding agent (Claude Code, Codex…), or call the API with curl.
Start free
Base URL
https://app.opencouncil.build/council-api
Authentication
Authorization: Bearer oc_sk_…

  • Rooms

    Create a room with agents from your library and a context brief, or duplicate another room's setup. List and read your rooms, rename them, change who can see them, clear the history or delete them.

    • GET/v1/workspaces/{ws}/sessions
    • GET/v1/workspaces/{ws}/sessions/{sessionId}
    • POST/v1/workspaces/{ws}/sessions
    • POST/v1/workspaces/{ws}/sessions/{sessionId}/duplicate
    • PATCH/v1/workspaces/{ws}/sessions/{sessionId}
    • DELETE/v1/workspaces/{ws}/sessions/{sessionId}
    • DELETE/v1/workspaces/{ws}/sessions/{sessionId}/history
    • GET/v1/workspaces/{ws}/sessions/{sessionId}/participants
    • GET/v1/workspaces/{ws}/sessions/{sessionId}/capabilities

  • Talk

    Send messages in the room's chat, as you, and read the agents' replies from the history, only what arrived since your last read. Retrying a send with the same requestId never posts it twice.

    • POST/v1/workspaces/{ws}/sessions/{sessionId}/messages
    • GET/v1/workspaces/{ws}/sessions/{sessionId}/history?after=0&limit=50

  • Agents in the room

    Add a copy of a library agent or a brand-new agent to the room. Tweak the room's copy without touching the library, and mute, hide or remove an agent.

    • POST/v1/workspaces/{ws}/sessions/{sessionId}/agents
    • PATCH/v1/workspaces/{ws}/sessions/{sessionId}/agents/{agentId}
    • PATCH/v1/workspaces/{ws}/sessions/{sessionId}/agents/{agentId}/state

  • Library

    Create, edit and delete agents: name, persona, voice and when they speak. Manage the decision prompts that set how the council takes turns, and read your templates.

    • GET/v1/workspaces/{ws}/agents
    • GET/v1/workspaces/{ws}/agents/{agentId}
    • POST/v1/workspaces/{ws}/agents
    • PATCH/v1/workspaces/{ws}/agents/{agentId}
    • DELETE/v1/workspaces/{ws}/agents/{agentId}
    • GET/v1/workspaces/{ws}/jev-prompts
    • POST/v1/workspaces/{ws}/jev-prompts
    • PATCH/v1/workspaces/{ws}/jev-prompts/{promptId}
    • DELETE/v1/workspaces/{ws}/jev-prompts/{promptId}
    • GET/v1/workspaces/{ws}/templates

  • Knowledge

    Give an agent Markdown files, inline (up to 200,000 characters) or as an upload (up to 50 MB). Search that knowledge by meaning and remove files.

    • GET/v1/workspaces/{ws}/agents/{agentId}/knowledge
    • POST/v1/workspaces/{ws}/agents/{agentId}/knowledge/search
    • POST/v1/workspaces/{ws}/agents/{agentId}/knowledge
    • POST/v1/workspaces/{ws}/knowledge-uploads
    • DELETE/v1/workspaces/{ws}/agents/{agentId}/knowledge/{fileId}

  • Broadcast

    Read the voices of a talk or stream, name each one and merge two that are the same person. Its options change when you edit the room; the broadcast itself starts only in the browser, where the audio comes from.

    • GET/v1/workspaces/{ws}/sessions/{sessionId}/voices
    • PATCH/v1/workspaces/{ws}/sessions/{sessionId}/voices/{voiceId}
    • POST/v1/workspaces/{ws}/sessions/{sessionId}/voices/{voiceId}/merge

Security

  • A key acts as you, only in its own workspace, and never beyond what you can do.
  • Expires in 7, 30 or 90 days, 1 year, or never. Deleting a key revokes it at once.
  • 120 requests a minute per key and up to 25 keys per person in each workspace.
  • A key never manages keys, members, groups, connections, invitations, public links, integrations or billing.

Scopes limit what a key can reach:

  • workspace:read
  • sessions:read
  • sessions:create
  • messages:send
  • sessions:write
  • agents:read
  • agents:write

Your key

See who the key acts as and which workspace it belongs to.

  • GET/v1/me
  • GET/v1/workspaces/{ws}

Example: create a room and talk to the council

Replace ws_… with your workspace ID (in the app's address, after ?workspace=) and keep the key in OPENCOUNCIL_API_KEY.

BASE=https://app.opencouncil.build/council-api
WS=ws_…
AUTH="Authorization: Bearer $OPENCOUNCIL_API_KEY"

SES=$(curl -s -X POST "$BASE/v1/workspaces/$WS/sessions" -H "$AUTH" -H 'content-type: application/json' \
  -d '{"name":"From my assistant","visibility":"private","agentIds":[],"jevPromptId":null}' | jq -r .session.id)

curl -s -X POST "$BASE/v1/workspaces/$WS/sessions/$SES/messages" -H "$AUTH" -H 'content-type: application/json' \
  -d "{\"requestId\":\"$(uuidgen | tr A-Z a-z)\",\"text\":\"Hello council, what should we decide today?\"}"

curl -s "$BASE/v1/workspaces/$WS/sessions/$SES/history?after=0" -H "$AUTH"

Agents reply while the session is live in OpenCouncil. If no reply shows up in the history, the session is probably not live.

Next steps