{
  "openapi": "3.1.0",
  "info": {
    "title": "Darkly Energized API",
    "version": "1.0.0",
    "description": "Most endpoints require a Bearer token. Data API keys (de_live_) exist only on subscriptions sold before 2026-10; new access is the /x402/* endpoints, which need no key; project tokens (de_project_) from https://darklyenergized.com/projects. The /x402/* endpoints need no account \u2014 they are paid per call in USDC on Base.",
    "contact": {
      "name": "Darkly Energized",
      "url": "https://darklyenergized.com"
    }
  },
  "servers": [
    {
      "url": "https://darklyenergized.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/series": {
      "get": {
        "operationId": "listSeries",
        "summary": "List all available series",
        "description": "Returns a flat catalog of all available data series (raw signals and computed indicators). Supports filtering by category, source, and search.",
        "tags": ["Series"],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by category (e.g. Central Bank, Equities, Liquidity, Crypto, FX, Options)"
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by data source (e.g. FRED, Polygon, DarklyEnergized, BOK)"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Search series by name, ID, or description"
          }
        ],
        "responses": {
          "200": {
            "description": "Series catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/series/{id}": {
      "get": {
        "operationId": "getSeries",
        "summary": "Fetch data for a series",
        "description": "Fetch time-series data for any series by ID. Supports date range filtering, pagination, and summary mode.",
        "tags": ["Series"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Series ID (e.g. WALCL, CBDEO, SPY)"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Start date (YYYY-MM-DD)"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "End date (YYYY-MM-DD)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 500
            },
            "description": "Maximum number of data points to return"
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Cursor for pagination \u2014 return data points after this date"
          },
          {
            "name": "summary",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Return statistical summary instead of raw data points"
          }
        ],
        "responses": {
          "200": {
            "description": "Series data",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SeriesDataResponse"
                    },
                    {
                      "$ref": "#/components/schemas/SeriesSummaryResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/series/batch": {
      "post": {
        "operationId": "batchSeries",
        "summary": "Fetch multiple series in one call",
        "description": "Fetch data for up to 20 series in a single request. Deduplicates underlying signal fetches for efficiency.",
        "tags": ["Series"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/x402/series": {
      "get": {
        "operationId": "x402ListSeries",
        "summary": "List all available series (x402 pay-per-call)",
        "description": "Returns the detailed catalog of the computed series x402 serves. No authentication required \u2014 payment is handled via x402 protocol (USDC on Base). Cost: $0.01 per request.",
        "tags": ["x402"],
        "security": [],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by category"
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by data source"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search by name, ID, or description"
          }
        ],
        "responses": {
          "200": {
            "description": "Series catalog (after successful payment)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/x402/series/{id}": {
      "get": {
        "operationId": "x402GetSeries",
        "summary": "Fetch data for a computed series (x402 pay-per-call)",
        "description": "Fetch time-series data for a computed series by ID. No authentication required \u2014 payment via x402 protocol. Only Darkly Energized computed indicators are available. Cost per call: $0.10 for an aggregate series (cbdet, cbdeo, wresbal_plus, fed_drains), $0.05 for an individual central bank series (cb_usd_walcl, cb_usd_jpnassets, cb_usd_ecbassetsw, cb_usd_cncbbs, cb_usd_gbcbbs, cb_usd_chcbbs, cb_usd_cacbbs, cb_usd_krcbbs). Every series and its price is listed free at /.well-known/x402.json. A raw or unknown id is refused with 403 or 404 before any payment is asked for.",
        "tags": ["x402"],
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Computed series ID, lowercase (e.g. cbdeo, wresbal_plus, cb_usd_walcl)"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Start date (YYYY-MM-DD)"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "End date (YYYY-MM-DD)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 500
            },
            "description": "Maximum number of data points to return"
          },
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Cursor for pagination \u2014 return data points after this date"
          },
          {
            "name": "summary",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Return statistical summary instead of raw data"
          }
        ],
        "responses": {
          "200": {
            "description": "Series data (after successful payment)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SeriesDataResponse"
                    },
                    {
                      "$ref": "#/components/schemas/SeriesSummaryResponse"
                    }
                  ]
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "description": "Series is not one x402 serves (only computed series are). Returned before any payment is asked for.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/x402/series/batch": {
      "post": {
        "operationId": "x402BatchSeries",
        "summary": "Fetch multiple computed series (x402 pay-per-call)",
        "description": "Fetch data for up to 20 computed series in one call. No authentication required \u2014 payment via x402 protocol. Only Darkly Energized computed indicators are available. Cost: the sum of each distinct series price ($0.10 aggregate, $0.05 individual); a repeated id is charged once. Every series and its price is listed free at /.well-known/x402.json. A batch naming any series x402 does not serve is refused with 403 and `invalidIds` before any payment is asked for.",
        "tags": ["x402"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results (after successful payment)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResponse"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "description": "The batch names a series x402 does not serve; `invalidIds` lists them. Returned before any payment is asked for.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpRequest",
        "summary": "MCP endpoint",
        "description": "Model Context Protocol (MCP) endpoint using Streamable HTTP transport. Send JSON-RPC requests to interact with DarklyEnergized tools and resources from AI agents.",
        "tags": ["MCP"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "JSON-RPC 2.0 request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/projects": {
      "get": {
        "summary": "List your leads",
        "tags": ["Projects"],
        "security": [
          {
            "projectToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Your leads, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "leads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Lead"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid project token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Brief a project (create a draft lead)",
        "tags": ["Projects"],
        "security": [
          {
            "projectToken": []
          }
        ],
        "description": "Creates a DRAFT lead from the six answers. Nothing is billed. The response carries `url`; open it so the account holder can review and press Send. At most five open leads per account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Draft created",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Lead"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "next": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid project token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Open-lead cap reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Read one of your leads",
        "tags": ["Projects"],
        "security": [
          {
            "projectToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "The lead",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lead"
                }
              }
            }
          },
          "404": {
            "description": "Not found \u2014 leads are private to their account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Edit answers on one of your leads",
        "tags": ["Projects"],
        "security": [
          {
            "projectToken": []
          }
        ],
        "description": "Editable while DRAFT, NEW or REVIEWING. Once SCOPED the answers are what the Statement of Work is drafted from and are frozen (400).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated lead",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lead"
                }
              }
            }
          },
          "400": {
            "description": "No longer editable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with `de_live_` prefix, held by a subscription sold before 2026-10. New access needs no key: use the /x402/* endpoints."
      },
      "projectToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Free project token with `de_project_` prefix (tokens issued before the rename start with `de_lead_` and still work), issued to any verified account at /projects (one per account; regenerating revokes the previous). Can create, read and edit that account's projects and nothing else. Not interchangeable with a `de_live_` API key."
      }
    },
    "schemas": {
      "DataPoint": {
        "type": "object",
        "required": ["time", "value"],
        "properties": {
          "time": {
            "type": "string",
            "format": "date",
            "example": "2026-02-14"
          },
          "value": {
            "type": ["number", "null"],
            "example": 1.23,
            "description": "Null where the series has no value on that date (for example while a computed series warms up)."
          }
        }
      },
      "SeriesCatalogEntry": {
        "type": "object",
        "required": ["id", "name", "category", "frequency", "source"],
        "properties": {
          "id": {
            "type": "string",
            "example": "WALCL"
          },
          "name": {
            "type": "string",
            "example": "Federal Reserve Total Assets"
          },
          "category": {
            "type": "string",
            "example": "Central Bank"
          },
          "frequency": {
            "type": "string",
            "enum": ["daily", "weekly", "monthly", "continuous"],
            "example": "weekly"
          },
          "unit": {
            "type": "string",
            "example": "USD"
          },
          "source": {
            "type": "string",
            "example": "FRED"
          }
        }
      },
      "DataSummary": {
        "type": "object",
        "required": ["latest", "changes", "range", "count", "dateRange"],
        "properties": {
          "latest": {
            "type": "object",
            "properties": {
              "time": {
                "type": "string",
                "format": "date"
              },
              "value": {
                "type": ["number", "null"]
              }
            }
          },
          "changes": {
            "type": "object",
            "description": "Percent changes for standard periods; null where the series has too little data for that period",
            "additionalProperties": {
              "type": ["number", "null"]
            },
            "example": {
              "1W": 5.2,
              "1M": -3.1,
              "3M": 12.4,
              "6M": -8.7,
              "1Y": 15.3
            }
          },
          "range": {
            "type": "object",
            "properties": {
              "min": {
                "type": ["number", "null"]
              },
              "max": {
                "type": ["number", "null"]
              },
              "avg": {
                "type": ["number", "null"]
              }
            }
          },
          "count": {
            "type": "integer"
          },
          "dateRange": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      },
      "ApiMeta": {
        "type": "object",
        "required": ["timestamp"],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "type": "integer"
          },
          "dataRange": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "freshness": {
            "type": "object",
            "properties": {
              "lastObservation": {
                "type": "string",
                "format": "date"
              },
              "frequency": {
                "type": "string"
              },
              "isStale": {
                "type": "boolean"
              }
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "hasMore": {
                "type": "boolean"
              },
              "cursor": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              }
            }
          }
        }
      },
      "CatalogResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeriesCatalogEntry"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "SeriesDataResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "object",
            "required": ["id", "name", "description", "category", "frequency", "data"],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "frequency": {
                "type": "string"
              },
              "unit": {
                "type": "string"
              },
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DataPoint"
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "SeriesSummaryResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "object",
            "required": ["id", "name", "description", "summary", "interpretation"],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "frequency": {
                "type": "string"
              },
              "unit": {
                "type": "string"
              },
              "summary": {
                "$ref": "#/components/schemas/DataSummary"
              },
              "interpretation": {
                "type": "string",
                "example": "Federal Reserve Total Assets is at 6.78T, up 0.3% this week. All Federal Reserve Banks: Total Assets."
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": ["ids"],
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 20,
            "example": ["cbdeo", "cb_usd_walcl"]
          },
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "summary": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "BatchResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DataPoint"
                  }
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/ApiMeta"
          }
        }
      },
      "LeadInput": {
        "type": "object",
        "properties": {
          "dream": {
            "type": "string",
            "maxLength": 4000,
            "description": "What you want to make happen \u2014 the outcome, in the user's words, not the technology. The only answer required to send."
          },
          "whyNow": {
            "type": "string",
            "maxLength": 4000,
            "description": "Why now: what changed, or what it is costing to wait."
          },
          "users": {
            "type": "string",
            "maxLength": 4000,
            "description": "Who uses it and how often: roles, how many, how often."
          },
          "done": {
            "type": "string",
            "maxLength": 4000,
            "description": "What has to exist to call it done. Becomes the deliverables list and, later, the acceptance criteria the build is tested against."
          },
          "success": {
            "type": "string",
            "maxLength": 4000,
            "description": "Six months in, how the user will know it worked \u2014 the number or the change they would point at."
          },
          "worksWith": {
            "type": "string",
            "maxLength": 4000,
            "description": "What it must work with: existing systems, data, logins, vendors."
          },
          "existingCode": {
            "type": "string",
            "maxLength": 4000,
            "description": "Whether code already exists: where, what stack, who maintains it."
          },
          "constraints": {
            "type": "string",
            "maxLength": 4000,
            "description": "Deadline, compliance, security, anything non-negotiable."
          },
          "anythingElse": {
            "type": "string",
            "maxLength": 4000,
            "description": "Anything else: prior attempts, chosen platforms, things that are off the table."
          },
          "kinds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "web_app",
                "mobile_app",
                "api_integration",
                "automation",
                "data_analytics",
                "ai_agent",
                "infrastructure",
                "rescue_modernize",
                "compliance",
                "advisory",
                "not_sure"
              ]
            },
            "description": "What shape the project is. Pick any. web_app \u00b7 mobile_app \u00b7 api_integration \u00b7 automation (workflow) \u00b7 data_analytics (dashboards) \u00b7 ai_agent \u00b7 infrastructure (cloud, DevOps) \u00b7 rescue_modernize (an existing system) \u00b7 compliance (readiness) \u00b7 advisory (fractional CTO) \u00b7 not_sure."
          },
          "stage": {
            "type": "string",
            "enum": ["idea", "spec", "prototype", "live_product"],
            "description": "Where the user is starting from: idea \u00b7 spec (written) \u00b7 prototype \u00b7 live_product."
          },
          "budgetRange": {
            "type": "string",
            "enum": ["under_10k", "10k_50k", "50k_200k", "over_200k", "not_sure"],
            "description": "under_10k \u00b7 10k_50k \u00b7 50k_200k \u00b7 over_200k \u00b7 not_sure."
          },
          "timeline": {
            "type": "string",
            "enum": ["asap", "1_3_months", "3_6_months", "flexible", "fixed_date"],
            "description": "asap \u00b7 1_3_months \u00b7 3_6_months \u00b7 flexible \u00b7 fixed_date (then set timelineDate)."
          },
          "timelineDate": {
            "type": "string",
            "format": "date",
            "description": "The fixed date, when timeline is fixed_date."
          },
          "decision": {
            "type": "string",
            "enum": ["can_sign", "recommend", "exploring"],
            "description": "can_sign (the user can sign) \u00b7 recommend (recommends to someone who signs) \u00b7 exploring."
          },
          "agent": {
            "type": "string",
            "maxLength": 120,
            "description": "Name of the agent filling this in, if any. Recorded on the lead and on every version."
          },
          "inferred": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "dream",
                "whyNow",
                "kinds",
                "stage",
                "users",
                "done",
                "success",
                "worksWith",
                "existingCode",
                "constraints",
                "anythingElse"
              ]
            },
            "description": "Names of the answers the agent inferred from context rather than heard from the user. budgetRange, timeline, timelineDate and decision are never inferable. A human edit in the form clears the mark on that field."
          }
        },
        "additionalProperties": false
      },
      "Lead": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": ["DRAFT", "NEW", "REVIEWING", "SCOPED", "CONVERTED", "DECLINED"],
            "description": "DRAFT until a person presses Send in the form; the owner moves it through REVIEWING and SCOPED; CONVERTED once a Statement of Work was drafted from it."
          },
          "source": {
            "type": "string",
            "enum": ["form", "api", "agent"]
          },
          "agentName": {
            "type": ["string", "null"]
          },
          "users": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Who uses it and how often: roles, how many, how often."
          },
          "constraints": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Deadline, compliance, security, anything non-negotiable."
          },
          "submittedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "updatedAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The form for this lead. Open it in a browser to review and send \u2014 submission is a human step."
          },
          "dream": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "What you want to make happen \u2014 the outcome, in the user's words, not the technology. The only answer required to send."
          },
          "whyNow": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Why now: what changed, or what it is costing to wait."
          },
          "done": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "What has to exist to call it done. Becomes the deliverables list and, later, the acceptance criteria the build is tested against."
          },
          "success": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Six months in, how the user will know it worked \u2014 the number or the change they would point at."
          },
          "worksWith": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "What it must work with: existing systems, data, logins, vendors."
          },
          "existingCode": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Whether code already exists: where, what stack, who maintains it."
          },
          "anythingElse": {
            "type": ["string", "null"],
            "maxLength": 4000,
            "description": "Anything else: prior attempts, chosen platforms, things that are off the table."
          },
          "kinds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "web_app",
                "mobile_app",
                "api_integration",
                "automation",
                "data_analytics",
                "ai_agent",
                "infrastructure",
                "rescue_modernize",
                "compliance",
                "advisory",
                "not_sure"
              ]
            },
            "description": "What shape the project is. Pick any. web_app \u00b7 mobile_app \u00b7 api_integration \u00b7 automation (workflow) \u00b7 data_analytics (dashboards) \u00b7 ai_agent \u00b7 infrastructure (cloud, DevOps) \u00b7 rescue_modernize (an existing system) \u00b7 compliance (readiness) \u00b7 advisory (fractional CTO) \u00b7 not_sure."
          },
          "stage": {
            "type": ["string", "null"],
            "enum": ["idea", "spec", "prototype", "live_product"],
            "description": "Where the user is starting from: idea \u00b7 spec (written) \u00b7 prototype \u00b7 live_product."
          },
          "budgetRange": {
            "type": ["string", "null"],
            "enum": ["under_10k", "10k_50k", "50k_200k", "over_200k", "not_sure"],
            "description": "under_10k \u00b7 10k_50k \u00b7 50k_200k \u00b7 over_200k \u00b7 not_sure."
          },
          "timeline": {
            "type": ["string", "null"],
            "enum": ["asap", "1_3_months", "3_6_months", "flexible", "fixed_date"],
            "description": "asap \u00b7 1_3_months \u00b7 3_6_months \u00b7 flexible \u00b7 fixed_date (then set timelineDate)."
          },
          "timelineDate": {
            "type": ["string", "null"],
            "format": "date",
            "description": "The fixed date, when timeline is fixed_date."
          },
          "decision": {
            "type": ["string", "null"],
            "enum": ["can_sign", "recommend", "exploring"],
            "description": "can_sign (the user can sign) \u00b7 recommend (recommends to someone who signs) \u00b7 exploring."
          },
          "inferred": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "nda": {
            "description": "The account's non-disclosure agreement with Darkly Energized: whether one is in force and, if not, where the user signs the standard one. Relay it before the user shares anything sensitive; signing is the user's act in the browser.",
            "type": "object",
            "properties": {
              "inForce": {
                "type": "boolean"
              },
              "effectiveDate": {
                "type": "string",
                "format": "date",
                "description": "Present when in force."
              },
              "source": {
                "type": "string",
                "enum": ["signed", "attached"],
                "description": "Present when in force: signed in the app, or the user's own paper attached by Darkly Energized."
              },
              "documentId": {
                "type": "string",
                "format": "uuid"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "The NDA page: sign, or download the executed copy."
              }
            },
            "required": ["inForce", "url"]
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "NotFound": {
        "description": "Series not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "Payment required via x402 protocol. The `payment-required` header contains a base64-encoded JSON object with accepted payment methods, pricing, and wallet address. Use an x402-compatible client (e.g. @x402/fetch) to handle payment automatically.",
        "headers": {
          "payment-required": {
            "schema": {
              "type": "string"
            },
            "description": "Base64-encoded PaymentRequired object containing accepted payment schemes, network, asset, amount, and payTo address"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Daily rate limit exceeded",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Daily request limit"
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Remaining requests today"
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp when limit resets"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until limit resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Series",
      "description": "Unified data series endpoints \u2014 raw signals, market data, and computed indicators"
    },
    {
      "name": "x402",
      "description": "Pay-per-call endpoints for computed series using x402 protocol (USDC micropayments on Base). No authentication required. Rate limited to 200 requests per 5 minutes per IP."
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol endpoint for AI agent integration"
    },
    {
      "name": "Projects",
      "description": "Start a software project for Darkly Energized LLC to scope. Free; requires a project token, not a data API key. /api/v1/leads is an alias of /api/v1/projects."
    }
  ]
}