> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useblueprints.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Public API basics for Blueprints integrations.

The Blueprints API lets authenticated clients work with account-owned resources such as blueprints, orders, portfolio views, risk settings, and connected integrations.

## Base URL

```text theme={null}
https://api.useblueprints.ai
```

Use HTTPS for every request. Send and receive JSON unless an endpoint explicitly documents another response type.

## When to use the API

Use the API when you are building a service, backend job, internal tool, or approved integration that needs deterministic access to Blueprints data.

Use MCP instead when an AI client should help a person inspect or edit blueprints conversationally. MCP exposes tool schemas for AI clients; the API exposes HTTP endpoints for software integrations.

## Endpoint categories

* **System status**: liveness checks for basic uptime monitoring.
* **Market data**: read-only helpers for market search and supported input discovery.
* **Blueprints**: create draft blueprints, read their state, update metadata or visual definitions, deploy reviewed blueprints, and stop running blueprints.
* **Trading and account**: read orders, portfolio summaries, and account-level risk rules.
* **API keys**: create scoped keys from a web session, then list or revoke key metadata.

## Request basics

Authenticated requests use bearer tokens:

```bash theme={null}
curl https://api.useblueprints.ai/api/blueprints \
  -H "Authorization: Bearer bp_YOUR_API_KEY"
```

Mutation endpoints accept JSON request bodies:

```bash theme={null}
curl https://api.useblueprints.ai/api/blueprints \
  -X POST \
  -H "Authorization: Bearer bp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Election market watcher"}'
```

IDs are UUIDs. Account-owned resources are scoped to the authenticated account, so a valid ID from another account returns `404`.

API keys can be scoped to specific capabilities such as `blueprints:read`, `blueprints:write`, `blueprints:deploy`, `portfolio:read`, `risk:write`, or `api_keys:write`. A request with a valid key but missing scope returns `403`. API keys cannot create other API keys.

The API playground sends requests directly from your browser to the API. Paste your `Authorization: Bearer bp_...` header in the playground authentication control before sending authenticated requests. If you operate a custom docs domain, include that origin in the API CORS allowlist before relying on playground requests.

## Current scope

The API is intended for product clients and approved integrations. It is not a full public SDK yet, so treat endpoint shapes as versioned by the running product.

Public unauthenticated routes include health checks, careers form submissions, and BetterAuth infrastructure under `/api/auth/*` (for example sign-in, callbacks, JWKS, and session endpoints). Market-data helpers, account data, and mutations require authentication.

## Response model

Successful responses return JSON objects or arrays. Error responses include an HTTP status code and a message suitable for display or logging.

Common statuses:

* `400`: request validation failed
* `401`: authentication is missing or invalid
* `403`: the credential is valid but cannot perform the action
* `404`: the requested resource was not found or does not belong to the caller
* `429`: too many requests
* `500`: unexpected server error
* `503`: temporary service or upstream dependency issue