DocsPublic API

Public API

Repository API keys let external systems create chats and send follow-up messages to Codeq8.

API key

Open the repository menu in Codeq8, choose API key, then generate a key. Store it as a secret in the calling system.

Send the key as Authorization: Bearer $CODEQ8_API_KEY.

The key is scoped to one repository. Regenerating it invalidates the previous key immediately.

New keys are shown once. Codeq8 stores the token hash, not the secret.

Public API writes are rate-limited before request bodies are processed. When Codeq8 returns 429, wait for the Retry-After interval before retrying.

Create a thread

Creates a new chat. If external_key is supplied, Codeq8 creates or returns the active thread for that exact key in the API key repository. If a pull request number or URL is supplied, Codeq8 reuses the active PR thread when one already exists. The response includes created and thread.thread_id.

POST /api/v1/threads

curl https://codeq8.com/api/v1/threads \
  -H "Authorization: Bearer $CODEQ8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "example-org/example-repo",
    "title": "Checkout regression",
    "message": "Investigate the failing checkout test.",
    "run": true
  }'

JSON body

repository / workspace_repository: Optional guard. Must match the API key repository.
external_key: Optional opaque idempotency key. Exact string match, scoped to the API key repository.
title: Thread title for new chats.
message / initial_message: Initial message text.
pull_request_number: PR number in the API key repository.
pull_request_url: Alternative PR reference.
branch_name / branch: Branch target for the chat.
origin_issue_number: Issue number to link as the source.
origin_issue_url: Alternative issue reference.
source_type: Source label for the thread.
assigned_to / assignment.kind: Optional. Use a GitHub username or github_user to assign a newly created thread to a repository assignee.
assigned_to_github_login / assignment.github_username: Optional with assignment.kind=github_user. Must be assignable in the API key repository.
run: Starts a Codeq8 run when true.
dispatch: Alias for run.
metadata: Optional JSON object stored with the message.

Threads created through the public API start unassigned unless assigned_to names a GitHub username, or assignment.kind is github_user. GitHub user assignments are accepted only for users assignable in the API key repository.

Assignment fields apply only when Codeq8 creates a new thread. If external_keyor a pull request reference matches an existing active thread, Codeq8 keeps that thread's current assignment. A retry with run: true does not start another run for a reused external_key thread.

For automations that can retry, send a stable external_key for each external task, ticket, or record. Do not generate a new key for each retry of the same work item.

POST /api/v1/threads assigned to a GitHub user

curl https://codeq8.com/api/v1/threads \
  -H "Authorization: Bearer $CODEQ8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "example-org/example-repo",
    "title": "Checkout regression",
    "message": "Please review the checkout regression.",
    "assignment": {
      "kind": "github_user",
      "github_username": "example-reviewer"
    },
    "run": false
  }'

POST /api/v1/threads with external_key

curl https://codeq8.com/api/v1/threads \
  -H "Authorization: Bearer $CODEQ8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_key": "ticket:CHECKOUT-123",
    "title": "Checkout regression",
    "message": "Investigate the failing checkout test.",
    "run": true
  }'

POST /api/v1/threads for a PR

curl https://codeq8.com/api/v1/threads \
  -H "Authorization: Bearer $CODEQ8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pull_request_number": 42,
    "message": "CI failed on the integration suite. Please inspect.",
    "run": true
  }'

Find a PR thread

Returns the active Codeq8 thread linked to a pull request, without creating a chat or sending a message.

GET /api/v1/threads?pull_request_number={number}

curl "https://codeq8.com/api/v1/threads?pull_request_number=42" \
  -H "Authorization: Bearer $CODEQ8_API_KEY"

Query parameters

pull_request_number / pull_request_url: Required PR reference in the API key repository.
repository / workspace_repository: Optional guard. Must match the API key repository.
status: Optional. Defaults to active. Use all to include archives.
limit: Optional result limit from 1 to 50. Defaults to 1.

Send a message

Sends a message to an existing Codeq8 thread in the same repository as the API key.

POST /api/v1/threads/{threadId}/messages

curl https://codeq8.com/api/v1/threads/wct_123/messages \
  -H "Authorization: Bearer $CODEQ8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The ticket status changed to blocked. Continue from the new details.",
    "run": true
  }'

Path parameters

threadId: Thread ID returned by create or PR lookup.

JSON body

content: Message text.
message: Alternative message text or message object.
role: Optional. user or system.
run: Starts a Codeq8 run when true.
dispatch: Alias for run.
metadata: Optional JSON object stored with the message.

Archive a thread

Archives a thread in the API key repository. If a webhook only has a PR number, look up the thread first.

POST /api/v1/threads/{threadId}/archive

curl -X POST https://codeq8.com/api/v1/threads/wct_123/archive \
  -H "Authorization: Bearer $CODEQ8_API_KEY"

Path parameters

threadId: Thread ID returned by create or PR lookup.

No JSON body.

Self-hosted Codeq8 runs still use the repository workflow from the self-hosting setup guide.