API Overview

The PromptJang API uses JSON request and response bodies and supports API-key and session-token authentication.

Base URL

https://api.promptjang.net

Authentication

Authenticated product routes accept one of these methods:

Authorization: Bearer pj_live_YOUR_API_KEY

or

X-Session-Token: your-session-token

See Authentication for details.

/health, login, and the disabled signup compatibility route are public. The signup route always returns 403 and cannot create an account. Event ingestion requires an API key. Billing management routes require a session token and remain inactive while live billing is disabled. /api/v1/billing/webhook is reserved for signed Stripe webhook requests.

Content Type

All request bodies must be application/json. All responses are application/json.

CORS

The API allows cross-origin requests from https://app.promptjang.net only. Preflight OPTIONS requests are handled automatically.

Allowed headers: Authorization, X-Session-Token, Content-Type, X-Requested-With, X-Event-Type, X-Correlation-ID, and Idempotency-Key.

Common Patterns

IDs

All resource IDs are 32-character hex strings (128-bit crypto-random):

7a337feef0633bcfa20ae1b0ba3e0372

Delivery attempt IDs have a da_ prefix:

da_7a337feef0633bcfa20ae1b0ba3e0372

Timestamps

API records use Unix timestamps in seconds:

1785542400

Pagination

The event-list route supports limit and offset query parameters:

GET /api/v1/events?limit=50&offset=100

Default limit: 50. Maximum limit: 100.

Security Headers

All responses include:

Content-Security-Policy: default-src 'none'
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Cache-Control: no-store
Referrer-Policy: no-referrer

Error Responses

All errors follow the format:

{
  "error": "Human-readable error message"
}

See Error Codes for the full reference.

Endpoints Summary

Method	Path	Description
GET	/health	Health check
Auth
POST	/api/v1/auth/signup	Disabled compatibility route (403)
POST	/api/v1/auth/login	Login
POST	/api/v1/auth/logout	Logout (current session)
POST	/api/v1/auth/logout-all	Revoke all sessions
GET	/api/v1/auth/me	Get current user
Ingest
POST	/e/:endpoint_id	Ingest event
POST	/t/:target_id	Accept an item for any target kind
Organizations
GET	/api/v1/orgs	Get organization
PATCH	/api/v1/orgs	Update organization
Endpoints
GET	/api/v1/endpoints	List endpoints
POST	/api/v1/endpoints	Create endpoint
GET	/api/v1/endpoints/:id	Get endpoint
PATCH	/api/v1/endpoints/:id	Update endpoint
DELETE	/api/v1/endpoints/:id	Delete endpoint
Unified targets
GET	/api/v1/targets	List all targets
POST	/api/v1/targets	Create webhook, mailbox, or A2A target
GET	/api/v1/targets/:id	Get target
PATCH	/api/v1/targets/:id	Update target
DELETE	/api/v1/targets/:id	Delete target
POST	/api/v1/targets/:id/refresh	Refresh A2A Agent Card
Agent mailboxes
GET	/api/v1/mailboxes/:id/messages	List mailbox messages
GET	/api/v1/mailbox-messages/:message_id	Read message and payload
POST	/api/v1/mailbox-messages/:message_id/claim	Claim for five minutes
POST	/api/v1/mailbox-messages/:message_id/ack	Acknowledge owned claim
API Keys
GET	/api/v1/keys	List API keys
POST	/api/v1/keys	Create API key
DELETE	/api/v1/keys/:id	Delete API key
Events
GET	/api/v1/events	List events
GET	/api/v1/events/:id	Get event
POST	/api/v1/events/:id/replay	Replay event
Stats
GET	/api/v1/stats	Delivery statistics
Billing
POST	/api/v1/billing/checkout	Stripe checkout (503 while billing is disabled)
GET	/api/v1/billing/portal	Stripe portal (503 while billing is disabled)
GET	/api/v1/billing	Billing status and price
GET	/api/v1/billing/invoices	Invoice history
GET	/api/v1/billing/reconciliation	Local and Stripe usage comparison
GET	/api/v1/usage	Current accepted usage estimate

The Stripe webhook route is intentionally excluded from the customer endpoint summary.