promptconduit

docs / api-reference

API Reference

The PromptConduit REST API lives at https://api.promptconduit.dev and has one primary ingest endpoint: POST /v1/events/raw, which accepts schema-2 event envelopes from the CLI. All endpoints require an API key, and errors follow RFC 7807.

Authentication

Include your API key in the Authorization header:

http
Authorization: Bearer sk_your_api_key_here

POST /v1/events/raw

The primary ingest endpoint. Used by the CLI to forward raw events from AI tools. The server applies tool-specific adapters to normalize events into the canonical schema.

Request (JSON — envelope schema v2)

json
{
  "schema": 2,
  "event_id": "019f2850-1234-7000-8000-abcdefabcdef",
  "session_id": "9a402796-…",
  "prompt_id": "e28d55f7-…",
  "tool": "claude-code",
  "hook_event": "UserPromptSubmit",
  "captured_at": "2026-07-03T18:00:00Z",
  "cli_version": "0.9.0",
  "raw_event": { /* raw hook JSON from the AI tool, untouched */ },
  "enrichments": {
    "env":   { "host": "laptop", "os": "darwin", "arch": "arm64", "cwd": "/Users/you/my-project" },
    "trace": { "trace_id": "4bf9…", "span_id": "00f0…" },
    "vcs":   {
      "type": "github",
      "repo": "you/my-project",
      "repo_url": "https://github.com/you/my-project",
      "branch": "main",
      "commit": { "hash": "abc123", "message": "feat: x", "author": "You" },
      "dirty": false,
      "remote_url": "git@github.com:you/my-project.git"
    },
    "prompt": { "count": 3, "chars": 120, "words": 22 }
  }
}

enrichments is an extensible slug-keyed map of normalized context computed by the CLI (e.g. vcs, cost, prompt). Every slug is optional and unknown slugs are stored verbatim and ignored by readers, so new enrichments require no API change. Envelopes with schema < 2 are rejected.

Response

http
HTTP/1.1 202 Accepted
Content-Type: application/json

{ "ok": true }

Multipart Upload (with attachments)

When the event contains attachments (images, documents), the CLI sends a multipart request:

http
POST /v1/events/raw
Content-Type: multipart/form-data; boundary=---boundary

-----boundary
Content-Disposition: form-data; name="envelope"
Content-Type: application/json

{ ...envelope JSON... }

-----boundary
Content-Disposition: form-data; name="attachment_0"; filename="image.png"
Content-Type: image/png

<binary data>
-----boundary--

Error Format

Errors follow RFC 7807:

json
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://promptconduit.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}