Godpip API Reference

Godpip turns unclear human input into structured, model-ready intent. Version 1 serves the Human Bridge; the other capabilities are specified and return 501 until they launch.

Quickstart

Send a person's words exactly as written. Ask for augment to get their words back, untouched, followed by expert notes you can pass to any model.

curl -sS https://api.godpip.com/v1/bridge/translate \
  -H "Authorization: Bearer $GODPIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "need a landing page for my dog walking biz, something friendly, maybe show prices? not sure",
       "desired_output": "augment"}'

Send result.augmented_input to your model, show result.canonical_intent to your planner, and check warnings for anything the verifier corrected. The full field list is under Human Bridge.

Environments & keys

One base URL serves both environments. The key's prefix chooses the environment, so test traffic never touches live data or usage.

Send the key as a bearer token: Authorization: Bearer gp_live_…. Keys are scoped to one project; a key from one project can never read another project's requests or jobs.

Scopes

Each key carries scopes that limit what it can do. A standard key has bridge:write, jobs:read, jobs:write, webhooks:read, webhooks:write, feedback:write, models:read and usage:read, plus the write scope for each capability as it launches. A call without the right scope returns 403 PERMISSION_DENIED.

Storing keys

Keep keys in your secret manager, never in source code, logs or the browser. Use separate secrets for sandbox and production, for example GODPIP_API_KEY holding a gp_test_… key in development and staging and a gp_live_… key in production, next to GODPIP_API_BASE_URL=https://api.godpip.com/v1.

Versioning

• The major version is in the path: /v1. A breaking change ships as /v2; /v1 keeps working through a published deprecation window.
• Within v1, changes are additive only: new optional request fields, new response fields, new enum values on outputs. Clients should ignore fields they do not know.
• Requests reject unknown fields with 400 INVALID_REQUEST, so typos fail loudly.
• Every response carries "api_version": "v1". Before anything is removed, responses carry Deprecation and Sunset headers.
• The contract version (info.version, semver) changes with every contract change: minor for additive changes, patch for documentation only. Every version has a changelog entry, and CI rejects a contract change without a bump.
• Read the deployed version without a key: GET /healthz returns api_version and supported {min, max}; GET /v1/openapi.json returns the full contract.
• The OpenAPI 3.1 document is the source of truth: https://api.godpip.com/v1/openapi.json. Generate a typed client from it with any OpenAPI generator.

Headers

Response envelope

Every capability returns the same envelope. result holds the capability's own schema.

{
  "request_id": "req_6eEyby3S4fU7PbgxUr5ZhxaL",
  "api_version": "v1",
  "environment": "test",
  "status": "completed",                  // completed | queued | running
  "job_id": "job_AlmUvqqMMic2hZMp6aGRRQ5M",
  "result": { … },                        // present when status is completed
  "confidence": 0.91,                     // 0..1, calibrated
  "warnings": [ { "code": "HEDGE_RESTORED", "message": "…" } ],
  "usage": {
    "input_units": 1875, "output_units": 1183,
    "billable": [ { "unit": "bridge_unit", "quantity": 1 } ],
    "cost": 0.0, "currency": "USD"
  },
  "metadata": {}
}

warnings lists every correction Godpip's verifier made, for example a statement demoted from explicit to inferred. Nothing is changed silently.

Sync, async & jobs

Every call runs as a job. Sync-style calls wait for the job and return 200 with the result, up to 25 seconds or budget.max_latency_ms if lower. If the job is still running, the response is 202 with status: "queued" or "running" and a job_id; poll GET /v1/jobs/{job_id} until it reaches a final state.

Errors

Errors use one shape. recoverable tells a client whether a retry can succeed.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request failed schema validation.",
    "recoverable": false,
    "suggested_action": "…",
    "request_id": "req_…",
    "details": { "errors": [ { "loc": ["body", "input"], "msg": "Field required" } ] }
  }
}

Human Bridge

Request

Which output to ask for

Example: augment

curl -sS https://api.godpip.com/v1/bridge/translate \
  -H "Authorization: Bearer $GODPIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f9e9a-1b6e-4e0b-9d0a-2f3c4d5e6f70" \
  -d '{"input": "a short video ad for our coffee brand, like 15 sec, vertical, maybe with a dog",
       "desired_output": "augment"}'

Result fields

Verifier warning codes

EXPLICIT_DEMOTED, NEGATION_LOST, HEDGE_RESTORED, CONSTRAINT_DEMOTED, QUESTION_DEFERRED, AUTHORITY_REQUIRED, SOLUTION_HINTS_OMITTED, MEMORY_WRITE_DROPPED, EXPERT_NOTES_UNAVAILABLE, RESEARCH_NOT_AVAILABLE.

Jobs

Webhooks

Delivery

When a job ends, Godpip POSTs one event to every webhook in the same project and environment that subscribes to it. The body is a WebhookEvent:

{
  "id": "evt_3f9c2a7d1b8e4c6a0f5d2e17",
  "type": "job.completed",
  "created_at": "2026-10-05T14:03:11.204Z",
  "environment": "test",
  "data": {"job_id": "job_…", "request_id": "req_…", "capability": "bridge", "status": "completed"}
}

data holds ids and status only, plus error (code, message, recoverable) for job.failed. Fetch the result with GET /v1/jobs/{job_id}.

Verifying the signature

Algorithm: HMAC-SHA256, key = the endpoint's signing_secret, message = the t value, a dot, then the raw request body bytes exactly as received. Compare in constant time. Reject the event if t is more than 300 seconds from your clock.

import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    t, given = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)

Retries and dedupe

• Success is any 2xx within 10 seconds. A non-2xx status, a redirect (not followed), a timeout or a connection error is retried.
• Retries wait 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h and 8 h: nine attempts over about 15.7 hours, then the delivery is marked failed.
• Delivery is at least once and order is not guaranteed. Dedupe on the event id; a job produces at most one event per terminal status.
• Answer quickly with 2xx and do the work afterwards.

Feedback

Usage & models

Coming capabilities

These endpoints are fully specified in the OpenAPI document and return 501 UNSUPPORTED_CAPABILITY until they launch.

Client context & privacy

• Your platform and user context is used for the call and kept nowhere: it is never stored with the request, logged, cached, shared across customers, or used to train Godpip.
• While a job runs, its context is encrypted on the job and erased when the job ends; the database enforces this.
• Context does reach the model vendor for that call (no-storage settings on). Cover this in your own privacy terms.
• Health, financial, government-id and credential data classes require a declared purpose.
• Godpip never writes to your storage; it only suggests memory_writes.
• Request bodies follow the project's retention policy (default 30 days); usage and billing records are kept.

Limits & pricing

Changelog