openapi: 3.1.0
info:
  title: Blueprints API
  version: "1.0"
  description: API for approved Blueprints product clients and integrations. Account resources require bearer authentication.
servers:
  - url: https://api.useblueprints.ai
security:
  - sessionBearer: []
  - apiKeyBearer: []
tags:
  - { name: Health, description: Service status endpoints that do not require authentication. }
  - { name: Market data, description: Read-only helpers for finding supported market inputs. }
  - { name: Blueprints, description: "Create, inspect, update, deploy, and stop account-owned blueprints." }
  - { name: Orders, description: Read account order activity. }
  - { name: Portfolio, description: "Read account-level balances, positions, and portfolio summary data." }
  - { name: Risk rules, description: Read and update account-level trading safeguards. }
  - { name: API keys, description: Manage API keys used by trusted external integrations and MCP clients. }
paths:
  /health:
    get:
      tags: [Health]
      operationId: healthCheck
      summary: Health check
      description: Returns a lightweight liveness response. Use this for uptime checks that only need to know the API process is responding.
      security: []
      responses:
        "200": { description: API process is healthy., content: { application/json: { schema: { $ref: "#/components/schemas/Health" } } } }
  /api/polymarket:
    get:
      tags: [Market data]
      operationId: getPolymarketData
      summary: Search or fetch Polymarket data
      description: Search supported market inputs by text, slug, or token. This is read-only and unauthenticated.
      security: []
      parameters:
        - { name: query, in: query, schema: { type: string }, description: "Text search, for example Bitcoin or US election." }
        - { name: slug, in: query, schema: { type: string }, description: Event or market slug to fetch directly. }
        - { name: tokenId, in: query, schema: { type: string }, description: Token ID to resolve to its market. }
        - { name: top, in: query, schema: { type: integer, minimum: 1, maximum: 50 }, description: Number of top markets to return. Keep requests small; public market-data routes may be rate-limited. }
      responses:
        "200": { description: "Market search, market detail, price history, or order-book data depending on query parameters.", content: { application/json: { schema: {} } } }
  /api/crypto:
    get:
      tags: [Market data]
      operationId: getCryptoData
      summary: Fetch crypto market data
      description: Fetch supported crypto symbols, recent trade/price series, or kline data for strategy inputs. This is read-only and unauthenticated.
      security: []
      parameters:
        - { name: symbol, in: query, schema: { type: string }, example: BTCUSDT, description: Crypto symbol to fetch. }
        - { name: type, in: query, schema: { type: string, enum: [trades, klines, symbols] }, description: Response mode. Omit for a current symbol summary. }
        - { name: interval, in: query, schema: { type: string }, example: 1m, description: Kline interval when type is klines. }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100 }, example: 100, description: Maximum number of points or symbols to return. Keep requests small; public market-data routes may be rate-limited. }
        - { name: query, in: query, schema: { type: string }, description: Symbol search query when type is symbols. }
      responses:
        "200": { description: "Crypto symbol search, summary, or time-series data.", content: { application/json: { schema: {} } } }
  /api/blueprints:
    get:
      tags: [Blueprints]
      operationId: listBlueprints
      summary: List blueprints
      description: Returns the authenticated account's blueprints, including status and timestamps. API keys need the `blueprints:read` scope.
      responses:
        "200": { description: Account-owned blueprints., content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/Blueprint" } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Blueprints]
      operationId: createBlueprint
      summary: Create a blueprint
      description: Creates a draft blueprint. API keys need the `blueprints:write` scope. You can create an empty blueprint with just a name, or provide an initial visual definition.
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/CreateBlueprint" } } } }
      responses:
        "200": { description: Created draft blueprint., content: { application/json: { schema: { $ref: "#/components/schemas/Blueprint" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/blueprints/{id}:
    parameters:
      - { $ref: "#/components/parameters/Id" }
    get:
      tags: [Blueprints]
      operationId: getBlueprint
      summary: Get a blueprint
      description: Returns one blueprint owned by the authenticated account, including its visual definition, deployment status, and current node state when available. API keys need the `blueprints:read` scope.
      responses:
        "200": { description: Blueprint detail., content: { application/json: { schema: { $ref: "#/components/schemas/Blueprint" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
    put:
      tags: [Blueprints]
      operationId: updateBlueprint
      summary: Update a blueprint
      description: Updates blueprint metadata or draft visual state. API keys need the `blueprints:write` scope. Active blueprints can reject edits; stop the blueprint first if the product requires a safer edit flow.
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/UpdateBlueprint" } } } }
      responses:
        "200": { description: Updated blueprint., content: { application/json: { schema: { $ref: "#/components/schemas/Blueprint" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/blueprints/{id}/deploy:
    post:
      tags: [Blueprints]
      operationId: deployBlueprint
      summary: Deploy a blueprint
      description: Starts a reviewed blueprint. API keys need the `blueprints:deploy` scope. The response includes the updated status and deployment identifier when deployment succeeds.
      parameters:
        - { $ref: "#/components/parameters/Id" }
      responses:
        "200": { description: Blueprint after deployment., content: { application/json: { schema: { $ref: "#/components/schemas/Blueprint" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/blueprints/{id}/stop:
    post:
      tags: [Blueprints]
      operationId: stopBlueprint
      summary: Stop a blueprint
      description: Stops a running blueprint or returns the existing blueprint state if it is already stopped. API keys need the `blueprints:deploy` scope.
      parameters:
        - { $ref: "#/components/parameters/Id" }
      responses:
        "200": { description: Blueprint after stop request., content: { application/json: { schema: { $ref: "#/components/schemas/Blueprint" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/orders:
    get:
      tags: [Orders]
      operationId: listOrders
      summary: List orders
      description: Returns account order activity for review and monitoring. API keys need the `orders:read` scope. Results are scoped to the authenticated account.
      responses:
        "200": { description: Account orders., content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/Order" } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/orders/{id}/approve:
    post:
      tags: [Orders]
      operationId: approveOrder
      summary: Approve an order
      description: Approves a pending order intent owned by the authenticated account. API keys need the `orders:write` scope.
      parameters:
        - { $ref: "#/components/parameters/Id" }
      responses:
        "200": { description: Order was approved., content: { application/json: { schema: { type: object, properties: { ok: { type: boolean, const: true }, id: { type: string, format: uuid } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/portfolio:
    get:
      tags: [Portfolio]
      operationId: getPortfolioOverview
      summary: Get portfolio overview
      description: Returns account-level portfolio summary data such as running blueprints, open positions, pending orders, and aggregate PnL. API keys need the `portfolio:read` scope.
      responses:
        "200": { description: Portfolio overview., content: { application/json: { schema: { $ref: "#/components/schemas/Portfolio" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/portfolio/positions/close:
    post:
      tags: [Portfolio]
      operationId: closePortfolioPosition
      summary: Close a position
      description: Creates a sell order intent to close part of an account position. API keys need the `portfolio:write` scope. Review the current position before calling this endpoint.
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [tokenId, amount], properties: { tokenId: { type: string }, amount: { type: number, exclusiveMinimum: 0 } } } } } }
      responses:
        "200": { description: Close-position intent was queued., content: { application/json: { schema: { type: object, properties: { intentId: { type: string, format: uuid }, status: { type: string }, amount: { type: number } } } } } }
        "400": { description: Request is invalid for the current position., content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/risk-rules:
    get:
      tags: [Risk rules]
      operationId: getRiskRules
      summary: Get risk rules
      description: Returns account-level trading safeguards used before live trading actions are allowed. API keys need the `risk:read` scope.
      responses:
        "200": { description: Current risk rules., content: { application/json: { schema: { $ref: "#/components/schemas/RiskRules" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    put:
      tags: [Risk rules]
      operationId: updateRiskRules
      summary: Update risk rules
      description: Updates account-level safeguards such as order size, daily loss, open position, order-rate, cooldown, and approval thresholds. API keys need the `risk:write` scope.
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/RiskRules" } } } }
      responses:
        "200": { description: Updated risk rules., content: { application/json: { schema: { $ref: "#/components/schemas/RiskRules" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/api-keys:
    get:
      tags: [API keys]
      operationId: listApiKeys
      summary: List API keys
      description: Lists keys created by the authenticated account. API keys need the `api_keys:read` scope.
      responses:
        "200": { description: API key metadata. Plaintext key values are never returned after creation., content: { application/json: { schema: { type: array, items: { $ref: "#/components/schemas/ApiKey" } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [API keys]
      operationId: createApiKey
      summary: Create an API key
      description: Creates a new scoped key for trusted integrations and MCP clients. This endpoint accepts web session tokens only; API keys cannot create other API keys. The plaintext `bp_` key is returned once; store it immediately.
      security:
        - sessionBearer: []
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [name], properties: { name: { type: string, minLength: 1, maxLength: 200 }, scopes: { type: array, items: { $ref: "#/components/schemas/ApiKeyScope" }, description: "Scopes granted to the new key. Send explicit least-privilege scopes for API-created keys." } } } } } }
      responses:
        "200": { description: Created API key including one-time plaintext key., content: { application/json: { schema: { $ref: "#/components/schemas/ApiKeyCreated" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /api/api-keys/{id}:
    delete:
      tags: [API keys]
      operationId: revokeApiKey
      summary: Revoke an API key
      description: Revokes a key owned by the authenticated account. API keys need the `api_keys:write` scope.
      parameters:
        - { $ref: "#/components/parameters/Id" }
      responses:
        "200": { description: Key was revoked or was already revoked., content: { application/json: { schema: { type: object, properties: { revoked: { type: boolean, const: true } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
components:
  securitySchemes:
    sessionBearer:
      type: http
      scheme: bearer
      bearerFormat: "Web session token"
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: "bp_ API key"
      x-default: "bp_YOUR_API_KEY"
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: Resource UUID.
      schema: { type: string, format: uuid }
  responses:
    Unauthorized: { description: "Missing, invalid, revoked, or expired credentials.", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    Forbidden: { description: Credential is valid but cannot perform this action., content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    NotFound: { description: Resource was not found or does not belong to the authenticated account., content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
  schemas:
    Health: { type: object, properties: { status: { type: string, example: ok } } }
    Error: { type: object, properties: { error: { type: object, properties: { message: { type: string } } }, message: { type: string } } }
    Json: {}
    Blueprint:
      type: object
      required: [id, name, status, createdAt, updatedAt]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        status: { type: string, enum: [draft, running, error, stopped] }
        deploymentId: { type: [string, "null"] }
        visual: { $ref: "#/components/schemas/Json" }
        nodeStates: { $ref: "#/components/schemas/Json" }
        error: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    CreateBlueprint: { type: object, required: [name], properties: { name: { type: string }, visual: { $ref: "#/components/schemas/Json" }, thesisId: { type: string, format: uuid } } }
    UpdateBlueprint: { type: object, properties: { name: { type: string }, visual: { $ref: "#/components/schemas/Json" } } }
    Order: { type: object, properties: { id: { type: string, format: uuid }, blueprintId: { type: string, format: uuid }, status: { type: string }, side: { type: string }, amount: { type: number }, createdAt: { type: string, format: date-time } } }
    Portfolio: { type: object, properties: { runningBlueprints: { type: number }, openPositions: { type: number }, pendingOrders: { type: number }, totalPnl: { type: number } } }
    RiskRules: { type: object, properties: { maxOrderSize: { type: number }, maxDailyLoss: { type: number }, maxOpenPositions: { type: number }, maxOrdersPerMinute: { type: number }, cooldownAfterLossSec: { type: number }, requireApprovalAbove: { type: number } } }
    ApiKeyScope: { type: string, enum: [blueprints:read, blueprints:write, blueprints:deploy, orders:read, orders:write, portfolio:read, portfolio:write, risk:read, risk:write, api_keys:read, api_keys:write] }
    ApiKey: { type: object, properties: { id: { type: string, format: uuid }, name: { type: string }, scopes: { type: array, items: { $ref: "#/components/schemas/ApiKeyScope" } }, createdAt: { type: string, format: date-time }, lastUsedAt: { type: [string, "null"], format: date-time }, revokedAt: { type: [string, "null"], format: date-time } } }
    ApiKeyCreated: { allOf: [{ $ref: "#/components/schemas/ApiKey" }, { type: object, properties: { key: { type: string, example: bp_YOUR_API_KEY } } }] }