Skip to main content
everything connected Claude can change through the settings tools is also a REST route for your own code. send your API key, and Edgeful writes the same rows the app reads: bookmarks, watchlists, account defaults, custom sessions, report customizations and templates land exactly as if you had edited them by hand, and the app shows them after a reload. nine more routes build, revise and run custom report drafts, and list, run, read, save and delete your saved custom reports.

your key and the write permission

  1. create a key in the API dashboard and send it as Authorization: Bearer <your-api-key> on every request, as for any other call. only an API key works here: a browser session does not. every route acts on the account that owns the key; there is no member id to pass.
  2. writes are on by default, and one permission covers Claude and your own code. in the API dashboard, under let AI agents make changes in your account, allow changes through your API key covers every client that uses the key, whether that is Claude over MCP or your script over REST. turning it off keeps every read working, and GET /v1/settings reports writes_enabled for the key you sent.
  3. the reads work on any API-enabled plan with writes off; the writes need the permission.

endpoints

each route has the same name as the MCP tool it mirrors, except run_custom_report_draft: Claude’s run_custom_report tool runs a saved report or a draft, and REST gives each its own route. a refusal message that names an operation (for example “list_report_catalog with surface screener lists them”) refers to this table. the full request and response shapes are in the API reference groups settings and custom reports in the sidebar.

try it

how writes behave

  • the app shows the change after reload. an Edgeful tab that was open before your write keeps its old copy of your bookmarks and watchlists and overwrites the change the next time it saves. a scheduled integration cannot reload that tab, so expect bookmark and watchlist additions made while you are in the app to be reverted by the tab’s next save until you reload it.
  • writes are idempotent change sets. a POST carries what to add and remove, or the fields to change, never a whole list to replace. adding a bookmark or ticker you already have, or removing one you do not, succeeds with status unchanged; creating a session or template equal to one you already saved converges on it. a write answers 200 with status created, updated, unchanged or deleted, and a repeated delete is unchanged, not 404, so resending a request after a timeout is always safe.
  • every result carries what undo needs. a defaults write returns the previous defaults, a customization write each key’s previous values (null when the key had none, so a reset undoes it) and a template update the previous template, and sending those back undoes the change. bookmark and watchlist writes return the previous and current lists and what changed, so removing what was added and adding what was removed undoes them. deletes return the removed object so it can be saved again under a new id. a custom-session save returns the saved session and the full list.
  • send writes one at a time. writes to one account serialize on your profile, so parallel requests only wait for each other.
  • Edgeful validates before it saves. report slugs and sub-reports come from the report catalog, tickers must be known on the market you name, a default session must be a standard session the report allows on that market, and a custom session needs HH:MM start and end times that differ and an IANA timezone. an invalid request is refused with 400 and a detail that lists the allowed values.
  • defaults are reconciled like the account form. the report constrains the market, a market change resets the ticker to that market’s default, and the session is re-resolved when the report no longer allows it.
  • report customizations land where the page reads them, in slots (value, value2, …) under the setting key, checked the way the page’s customization modal checks them; each record carries the key’s previous and resulting values and, per page, the query a report endpoint needs to apply them. the MCP settings page spells out the slot, template and What’s in Play rules in full; the REST routes apply exactly the same ones.
  • templates are applied in Edgeful. saving a template does not change any report page. it appears in its picker after a reload, or the app’s five-minute template refetch, and you apply it from there.
  • every write is logged with the operation, your member id and the key that made it. settings writes cost no AI credits.

errors and retries

two 400 messages mean retry rather than fix: “Ticker validation is temporarily unavailable; try again shortly.” and a customization that “was saved from Edgeful at the same time”. everything else under 400 needs a different request. honour Retry-After when it is present and back off otherwise; a tight retry loop on 429 burns the hourly budget, because refused attempts count. builds, revisions and draft runs answer with these statuses only for the first ten seconds. after that the response has started as a 200, so a later failure arrives in its body as status failed with a message: always read status. see long requests.

budgets and limits

  • settings writes share one budget per account of 60 per minute and 600 per hour across Claude’s MCP connections and every API key, so a script writing in a loop can leave Claude refused for the rest of the window, and the reverse. one request counts once however many items it carries, refused attempts count too, and each list is capped at 100 items.
  • custom-report runs, draft runs included, share a budget of 60 per minute and 600 per hour with Claude’s runs, and every run request counts, one that returns an existing result included. builds, revisions, saves and deletes share a budget of 10 per minute and 100 per hour with Claude’s.
  • builds and revisions use your Edgeful AI allowance, as they do in Claude and in Edgeful AI. runs, saves, deletes and reads use none.
  • a run that needs a fresh computation also uses your run allowance of 200 per hour, shared with builds in Edgeful, and fresh computations run one at a time per account: starting another while one computes is a 429 with run_limit_concurrent and retry_after_seconds, so start a dashboard’s runs one after another. a run already made for the same inputs and completed data uses neither. a draft run always computes, so it always uses both.
  • every call also counts against the key’s request limits from authentication: 120 per 60 seconds, 30 per 10 seconds and 1,500 per hour.
  • settings and custom-report calls do not appear in the API dashboard’s usage numbers, which count report calls.
  • reads are never budgeted.

custom reports over REST

everything Claude does with custom reports over MCP works here: build a draft from a brief, revise it, run it, save it, and then list, run, read and delete the saved report.
  • build and revise. POST /v1/custom-reports/drafts takes a plain-language brief and optionally the ticker, market_type and session to build on. Edgeful generates and validates the code; the route accepts none. status needs_clarification carries a question: answer it with POST /v1/custom-reports/drafts/{conversation_id}/revisions and your feedback. status succeeded carries the methodology, assumptions, accepted_controls and a sample_result with every row, plus the conversation_id and message_id that name the draft. send more feedback to the same revisions route to change it; each success returns a new message_id. the builder conversation also appears in your Edgeful AI history at the returned url.
  • run a draft. POST /v1/custom-reports/drafts/{conversation_id}/runs with the draft’s message_id runs it before you save, on its own inputs or on controls. the result comes back with every row and nothing is stored: there is no run_id to read again, and the draft is not saved.
  • list and read. GET /v1/custom-reports returns your saved reports with total, has_more and next_offset; pass next_offset as offset for the next page, and limit up to 100. GET /v1/custom-reports/{definition_id}/latest-result returns the latest successful stored result with the effective_controls, data_through and computed_at it actually used, or status no_result when no saved run has completed yet. neither starts a run.
  • every row. a result carries every row the run stored, with total_rows; Claude’s tools page the same rows a hundred at a time. a run whose result would exceed about 512 KB stores nothing and fails with “result too large - narrow the window.”
  • run. POST /v1/custom-reports/{definition_id}/runs runs the saved code on its saved inputs, or on controls that change the ticker, session or dates; the market and granularity stay locked, and runs use no AI credits. a run already made for the same inputs and completed data comes back at once with 200. otherwise the run starts and answers 202 with status running, its run_id and poll_after_seconds: read it with GET /v1/custom-reports/{definition_id}/runs/{run_id} until status is no longer running. a failed run with retryable true is retried by sending its run_id as retry_of_run_id with the same controls.
  • save and delete. POST /v1/custom-reports saves a reviewed draft, named by the conversation_id and message_id of a successful build here, in Claude or in Edgeful AI, under the name you give it. DELETE /v1/custom-reports/{definition_id} deletes a saved report and its stored runs; deleting it again is a 404.

long requests

a build or revision can take a few minutes and is stopped after ten; a draft run is stopped after three. each works only while your request stays connected, as Claude’s tool calls do.
  • set a long read timeout, ten minutes for a build, and do not send the request again while it runs: a second build is a second charge to your AI allowance, and a second revision of the same conversation is refused while the first is building.
  • the body may start with spaces. while the work runs Edgeful sends a space every ten seconds to keep the connection open, then the JSON result. JSON parsers skip leading whitespace, so response.json() and JSON.parse read it unchanged.
  • disconnecting cancels the work.
  • read status. a request refused in its first ten seconds answers with the status codes above. after that the response is a 200, and a failure arrives as {"status": "failed", "message": "..."}.

the playground sends real requests

the try it button on a write route changes your account, and on a delete route removes the template, session or custom report you name. settings results carry what undo needs, but a deleted custom report and its stored runs cannot be restored here. it is not a sandbox.

versioning

routes under /v1 only grow: new routes, fields and codes may appear without notice, and a documented route, field, status or code is not removed or renamed under /v1.