Register an LLM endpoint

LLM endpoints are the targets Penaxtra scans on a schedule. An endpoint is a logical record that binds together a base URL, authentication, expected wire format, and an asset owner.

Status: console-only today, API planned. Endpoint registration via the console (/app/endpoints/new) is the supported path. POST /api/v2/endpoints and POST /api/v2/endpoints/{id}/test are on the roadmap; the curl examples below describe the planned wire format so integrations can be designed against it. The OpenAPI document at /api/v2/openapi.json lists only routes that are live.

Step 1: Mint an API token

Sign in, then Settings → API tokens → New. Choose the endpoints:write scope. Tokens are sealed-box encrypted at rest; the cleartext is shown once on creation.

Step 2: Create the endpoint

curl -sS https://penaxtra.com/api/v2/endpoints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production customer chatbot",
    "url": "https://api.upstream-llm.example/v1/chat/completions",
    "wire_format": "chat_completions_v1",
    "model": "model-name-from-provider",
    "auth_header": "Authorization",
    "auth_value_secret_ref": "secret:upstream_llm_key",
    "owner_user_id": "current",
    "tags": ["customer-facing","kyc"]
  }'

Response:

{
  "id": "ep_2026_abc123",
  "name": "Production customer chatbot",
  "url": "https://api.upstream-llm.example/v1/chat/completions",
  "wire_format": "chat_completions_v1",
  "model": "model-name-from-provider",
  "status": "active",
  "created_at": "2026-05-22T10:14:00Z"
}

Step 3: Test the endpoint

curl -sS https://penaxtra.com/api/v2/endpoints/ep_2026_abc123/test \
  -H "Authorization: Bearer $TOKEN" \
  -X POST

A successful test returns the upstream response code, latency in milliseconds, and the wire-format check verdict. A failing test surfaces the specific reason (auth header missing, schema mismatch, TLS failure).

Common errors

Code	Meaning	Fix
`400 invalid_wire_format`	The `wire_format` field is unknown	Use one of: `chat_completions_v1`, `text_completions_v1`, `messages_v1`, `custom_template`
`403 missing_scope`	API token lacks `endpoints:write`	Mint a new token with the right scope
`409 url_duplicate`	An endpoint with the same URL already exists	Use PATCH to update the existing record
`422 secret_ref_unknown`	The referenced secret does not exist in the workspace secret store	Create it under Settings → Secrets first

Security notes

The endpoint URL is stored cleartext; treat it as workspace-visible metadata.
The auth credential is stored as a sealed-box reference (secret:<name>). The actual value never lands in the endpoint row.
Test requests honour the same DLP filters as live scans. A test request that triggers a DLP block returns 422 with the matched rule id.

Last reviewed: 2026-06-13. Reviewed by: Engineering. Content type: Developer documentation. Reach the maintainers: [email protected] .

Step 1: Mint an API token

Step 2: Create the endpoint

Step 3: Test the endpoint

Common errors

Security notes

Related