HTTP API¶

The HTTP API is the language-neutral interface to a running PowerContext Server. The default base URL is http://127.0.0.1:8000.

If you are integrating PowerContext into your own AI application rather than looking up one field, start with the HTTP API lifecycle tutorial. This page remains the path, contract, and error-semantics reference.

Discover the contract¶

With a local unauthenticated Server running, open:

• /docs for interactive Swagger UI;
• /redoc for ReDoc;
• /openapi.json for the contract served by that process.

The checked-in source of truth is openapi/powercontext.yaml. Use it when generating a client or reviewing every request and response field. When Server authentication is enabled, the three discovery routes require the same bearer token as other protected routes. A browser address bar cannot add that header: use a trusted proxy or browser setup that injects it, or download /openapi.json with an authenticated command after setting the variables below. Never put the token in the URL.

Authenticate requests¶

Authentication is disabled for the default loopback-only installation. When the operator enables it, include this header on API and MCP requests:

Authorization: Bearer <token>

The examples below use an optional shell variable:

POWERCONTEXT_URL=http://127.0.0.1:8000
POWERCONTEXT_AUTH_HEADER="Authorization: Bearer ${POWERCONTEXT_CLIENT_API_TOKEN}"

Omit --header "$POWERCONTEXT_AUTH_HEADER" when authentication is disabled. The /health/live and /health/ready endpoints are always public. See Deploy the Server before allowing remote access.

For an authenticated Server, download the exact contract served by that process with:

curl --fail \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --output powercontext-openapi.json \
  "$POWERCONTEXT_URL/openapi.json"

Store and search one Memory¶

Choose a stable scope_id for the project or tenant. Reuse it across sessions; a session ID is not a durable project identity.

Store one already-curated Memory entry:

curl --fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --data '{
    "scope_id": "project:example",
    "kind": "decision",
    "text": "Keep the public API asynchronous."
  }' \
  "$POWERCONTEXT_URL/v1/memory/remember"

The response contains an exact citation. Keep that citation when a later request must revise, retire, or read that specific immutable revision.

Search active entries in the same scope:

curl --fail \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "$POWERCONTEXT_AUTH_HEADER" \
  --data '{
    "scope_id": "project:example",
    "query": "public API",
    "limit": 5
  }' \
  "$POWERCONTEXT_URL/v1/memory/search"

Find an operation¶

The OpenAPI contract defines the complete path list, schemas, limits, and status codes. The higher-level workflow and Python examples are in Interfaces.

Handle errors and concurrent changes¶

Errors use one JSON envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "The request violates the API contract.",
    "details": {}
  }
}

Common statuses are:

Every response includes X-PowerContext-Request-ID; record it when diagnosing a failed call. Preserve exact citations for Memory revision and retirement. Candidate review writes require the current expected_version; after a 409, read the Candidate again before deciding whether to retry.