API reference

All requests go to the PlainField gateway at https://api.plainfield-ai.com. Every endpoint is authenticated with your PlainField API key, sent as Authorization: Bearer pt_live_....

Chat completions

POST /ai/chat/completions

The unified, OpenAI-compatible chat endpoint. The provider is chosen by the provider/model prefix in the model field.


curl -X POST https://api.plainfield-ai.com/ai/chat/completions \
  -H 'Authorization: Bearer pt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The response is a standard OpenAI chat completion. Streaming is supported by setting "stream": true.

Metadata headers

These headers are stripped before forwarding to the provider and stored with the log entry, so you can group usage by prompt, session, or user.

Header	Description
`plainfield-prompt-id`	Group requests by prompt template.
`plainfield-session-id`	Group requests by user session.
`plainfield-user-id`	Track requests by end user.

Passthrough parameters

Standard OpenAI-format inference parameters pass through untouched. PlainField does not inject or modify them:

temperature · max_tokens · top_p · top_k · frequency_penalty · presence_penalty · stop · stream

Response headers

PlainField may include these headers on the response:

Header	Description
`X-Plainfield-Provider`	The provider that served the request.
`X-Plainfield-Provider-Request-Id`	The provider’s request id.

REST API

The REST API reads your recent requests and cost summary. It uses the same API key as the chat endpoint.

GET /api/logs

Recent log entries, most recent first (default limit 100).

Query params: start, end (RFC3339), model, provider, limit, offset.


curl 'https://api.plainfield-ai.com/api/logs?limit=10&provider=openai' \
  -H 'Authorization: Bearer pt_live_...'

GET /api/logs/:id

A single log entry by UUID.


curl 'https://api.plainfield-ai.com/api/logs/<uuid>' \
  -H 'Authorization: Bearer pt_live_...'

GET /api/costs

A cost summary broken down by model.


curl 'https://api.plainfield-ai.com/api/costs?start=2026-01-01T00:00:00Z' \
  -H 'Authorization: Bearer pt_live_...'


{
  "total_requests": 42,
  "total_cost_usd": 0.0123,
  "total_input_tokens": 10000,
  "total_output_tokens": 5000,
  "by_model": {
    "gpt-4o-mini": { "requests": 42, "cost_usd": 0.0123, "input_tokens": 10000, "output_tokens": 5000 }
  }
}