Convexly Public API

The Convexly REST API lets you create decisions, record outcomes, and retrieve insights programmatically. Perfect for integrations with Slack, Chrome extensions, Zapier, and custom workflows.

Base URL: https://api.convexly.app/api/v1/public

Interactive API Explorer (Swagger)|ReDoc

Authentication

All public API endpoints require an API key passed via the X-API-Key header. Generate keys from Settings → API Keys.

curl -H "X-API-Key: cvx_your_api_key_here" \
  https://api.convexly.app/api/v1/public/decisions

Keep your API key secret. It grants full access to your decisions. If a key is compromised, revoke it immediately from the Settings page.

Decisions

POST/decisions

Create a new decision.

Request Body

{
  "title": "Launch new feature",       // required, max 200 chars
  "description": "Context for the decision",
  "probability": 0.7,                  // required, 0-1
  "best_case": 5000,                   // best-case outcome value
  "expected_case": 2000,               // expected outcome value
  "worst_case": -1000,                 // worst-case outcome value
  "category": "product",               // optional, max 50 chars
  "tags": ["q1", "growth"],            // optional array
  "source": "api"                      // optional, default "api"
}

Response (201)

{
  "decision": {
    "id": "uuid",
    "title": "Launch new feature",
    "probability": 0.7,
    "status": "active",
    "created_at": "2026-03-07T12:00:00Z",
    ...
  }
}

GET/decisions

List your decisions, newest first.

Query Parameters

limit — Max results (1-100, default 50)

offset — Skip N results (pagination)

Response (200)

{
  "decisions": [ ... ],
  "count": 25
}

GET/decisions/{id}

Get a specific decision with its outcomes.

Response (200)

{
  "decision": {
    "id": "uuid",
    "title": "Launch new feature",
    "probability": 0.7,
    "outcomes": [ ... ],
    ...
  }
}

Outcomes

POST/decisions/{id}/outcome

Record the outcome of a decision.

Request Body

{
  "result": "success",     // "success", "failure", or descriptive string
  "notes": "Shipped on time, 20% adoption in week 1"
}

Response (201)

{
  "outcome": {
    "id": "uuid",
    "decision_id": "uuid",
    "result": "success",
    "recorded_at": "2026-03-07T12:00:00Z"
  }
}

Insights

GET/insights

Get a behavioral insights summary including Brier score and calibration stats.

Response (200)

{
  "total_decisions": 42,
  "resolved_decisions": 18,
  "average_brier_score": 0.1823,
  "generated_at": "2026-03-07T12:00:00Z"
}

Key Management

Key management endpoints use JWT authentication (your Supabase session), not API keys. These are used by the Settings page to manage keys.

POST/keys

Generate a new API key. The raw key is returned once and cannot be retrieved again.

Request Body

{
  "label": "My Slack integration"   // optional, default "default"
}

Response (201)

{
  "raw_key": "cvx_abc123...",
  "key_id": "uuid",
  "label": "My Slack integration",
  "created_at": "2026-03-07T12:00:00Z",
  "message": "Store this key securely -- it will not be shown again."
}

GET/keys

List your API keys (shows last 4 characters only).

Response (200)

{
  "keys": [
    {
      "id": "uuid",
      "label": "My Slack integration",
      "key_preview": "3xyz",
      "revoked": false,
      "last_used_at": "2026-03-07T10:00:00Z",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}

DELETE/keys/{key_id}

Revoke an API key. The key will immediately stop working.

Response (200)

{
  "revoked": true,
  "key_id": "uuid"
}

Rate Limits

Free plan

100 requests/hour

Pro plan

1,000 requests/hour

Team plan

5,000 requests/hour

Enterprise plan

Unlimited

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset

Code Examples

Create a decision

curl -X POST https://api.convexly.app/api/v1/public/decisions \
  -H "X-API-Key: cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Expand to EU market",
    "probability": 0.65,
    "best_case": 50000,
    "expected_case": 20000,
    "worst_case": -10000,
    "category": "strategy"
  }'

List decisions

curl https://api.convexly.app/api/v1/public/decisions?limit=10 \
  -H "X-API-Key: cvx_your_key"

Record an outcome

curl -X POST https://api.convexly.app/api/v1/public/decisions/{id}/outcome \
  -H "X-API-Key: cvx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"result": "success", "notes": "Shipped on schedule"}'

Error Responses

401

Missing or invalid API key

404

Decision not found (or doesn't belong to you)

422

Validation error (missing or invalid fields)

429

Rate limit exceeded

502

Upstream database error

Need help? Manage API keys · Go to Dashboard

Download OpenAPI Spec (JSON)