DocsAPI Reference

API Reference

All Specter API endpoints with request/response examples.

Base URL

https://specter.draftlabs.org

Authentication

Signal ingestion endpoints use API key authentication. Pass your product's API key in the x-api-key header or as a key query parameter.

Method	How to Pass	Endpoints
Header	`x-api-key: spk_abc123...`	`/api/signals`, `/api/proposals`
Query param	`?key=spk_abc123...`	`/api/ingest`

Find your API key in Settings → Products after creating a product. Keys are prefixed with spk_.

POST/api/signals

Send one or more user signals. Supports single objects and batch arrays.

Headers

`x-api-key`required	string	Product API key
`Content-Type`required	string	`application/json`

Body (single signal)

`type`required	string	Signal type (1–100 chars). E.g. `thumbs_up`, `error`
`payload`	object	Arbitrary JSON data about the event
`context_id`	uuid	Route signal to a specific context

Example

Requestbash

curl -X POST https://specter.draftlabs.org/api/signals \
  -H "Content-Type: application/json" \
  -H "x-api-key: spk_your_key_here" \
  -d '[
    {"type": "swap_completed", "payload": {"token": "ETH", "amount": 1.5}},
    {"type": "thumbs_up", "payload": {"feature": "chart"}}
  ]'

Response \u2014 200 OKjson

{ "received": 2 }

Error Responses

401Missing or invalid API key

400Invalid JSON or missing signal type

429Monthly signal limit exceeded

POST/api/ingest

Flexible signal ingestion for automation tools (Zapier, Make.com, n8n). API key via query param or header.

Body

`type \| event \| event_type`required	string	Signal type (any of these field names accepted)
`payload \| data \| properties`	object	Event data (any of these field names accepted)
`context_id`	uuid	Route to a specific context

Examplebash

curl -X POST "https://specter.draftlabs.org/api/ingest?key=spk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "purchase", "data": {"amount": 49.99}}'

Response \u2014 200 OKjson

{ "received": 1 }

GET/api/proposals

Retrieve proposals for your product. Supports session auth (dashboard) and API key auth.

Query Parameters

`status`	string	Filter by status: `pending`, `approved`, `rejected`, `deferred`
`limit`	number	Max results (default: 50)

Example with API keybash

curl https://specter.draftlabs.org/api/proposals?status=pending \
  -H "x-api-key: spk_your_key_here"

Response \u2014 200 OKjson

[
  {
    "id": "uuid",
    "product_id": "uuid",
    "context_id": "uuid",
    "status": "pending",
    "priority_score": 78,
    "diagnosis": "High cart abandonment rate detected...",
    "current_state": "Context: checkout-flow\nPositive: 42.5%...",
    "proposed_change": "Add progress indicator to checkout steps...",
    "evidence_summary": "68% of signals are cart_abandoned...",
    "predicted_impact": "Expected 15-20% reduction in abandonment...",
    "signal_count": 156,
    "created_at": "2026-03-05T12:00:00Z"
  }
]

POST/api/products

Create a new product and receive an API key. Requires session authentication. Enforces plan-based product limits.

Body

namerequired

string

Product name (1–100 chars)

Response \u2014 200 OKjson

{
  "id": "uuid",
  "name": "My DeFi App",
  "api_key": "spk_a1b2c3d4e5f6..."
}

403Product limit reached for your plan

Contexts API

CRUD operations for contexts. All require session authentication.

POST/api/context

Create a new context for a product.

`product_id`required	uuid	Product to attach context to
`name`required	string	Context label (e.g. `checkout-flow`)
`content`required	string	Description of what this product area does
`positive_signals`	string[]	Signal types that indicate success
`negative_signals`	string[]	Signal types that indicate failure

GET/api/context

List all contexts for the authenticated user.

PATCH/api/context

Update an existing context. Pass id plus any fields to update.

DELETE/api/context?id=uuid

Permanently remove a context.

Rate Limits

Signal ingestion is rate-limited by your subscription plan:

Plan	Signals/mo	Proposals/mo	Products
Free	500	3	1
Builder ($29)	5,000	10	1
Growth ($99)	50,000	Unlimited	5
Scale ($299)	500,000	Unlimited	Unlimited

Analyze Now & Pricing