Skip to content
Spec

Connect the stock market to ChatGPT, Claude, Grok, Cursor, Codex, or Perplexity

Agent-first investment infrastructure for opportunity discovery, optimization, and execution.

Work in the agent you already trust.

Drop Providence into ChatGPT, Claude, Cursor, or any other agent and it can read the market, find the trade, and act. No new dashboard.

Live prices, history, and execution in the same conversation. Copy the prompt, authenticate, and start asking.

Specification
Providence API 0.1.0

Agent-ready by design.

Run backtests, test strategies, and explore opportunities in minutes.

System2 endpoints
get/healthCheck API liveness
Public
Response 200HealthResponse
service *
enum(api)
status *
enum(ok)
environment *
enum(dev | preview | prod)
correlationId *
string:uuid
Request correlation ID.

200

The API Worker process is up.

get/v1/healthCheck authenticated API health
Requires sign-in

Requires a WorkOS AuthKit access token with organization context and `account.read`.

Response 200AuthenticatedHealthResponse
service *
enum(api)
status *
enum(ok)
environment *
enum(dev | preview | prod)
correlationId *
string:uuid
Request correlation ID.
accountId *
string
Account TypeID (`acct_…`).
workosOrganizationId *
string
workosUserId *
string

200

Caller is authenticated and authorized for the resolved account.

401

Missing or invalid access token.

403

Authenticated but not permitted.

500

Unexpected server failure.

503

Authorization service unavailable.

Prices2 endpoints
get/v1/symbols/{ticker}/latest-priceGet the latest price for a symbol
Requires sign-in

Requires a WorkOS AuthKit access token and `stock_price.read` on the caller's account.

Parameters
ticker *path
Response 200LatestPriceResponse
accountId *
string
Account TypeID (`acct_…`).
symbolId *
string
Symbol TypeID (`sym_…`).
ticker *
string
price *
string
volume *
integer
recordedAt *
string:date-time
correlationId *
string:uuid
Request correlation ID.

200

Latest persisted observation for the ticker.

401

Missing or invalid access token.

403

Authenticated but not permitted.

404

Symbol or price observation was not found.

500

Unexpected server failure.

503

Authorization service unavailable.

get/v1/symbols/{ticker}/barsList historical 5-minute OHLCV bars for a symbol
Requires sign-in

Requires a WorkOS AuthKit access token and `stock_price.read` on the caller's account. Returns stored 5-minute bars only (no aggregation). `from`/`to` is a UTC instant window (max 7 days). Page with `cursor` using the same filters. Empty pages return 200.

Parameters
ticker *path
from *queryInclusive lower bound on bar_start (ISO-8601 datetime).
to *queryExclusive upper bound on bar_start (ISO-8601 datetime).
intervalqueryBar interval. v1 supports 5m only. Default 5m.
sessionquerySession filter. Default regular.
adjustmentqueryPrice adjustment. Default raw.
limitqueryPage size. Defaults to 500; max 2000.
cursorqueryOpaque pagination cursor from a previous nextCursor. Filter-bound to the request that issued it.
Response 200ListBarsResponse
accountId *
string
Account TypeID (`acct_…`).
symbolId *
string
Symbol TypeID (`sym_…`).
ticker *
string
interval *
enum(5m)
session *
enum(regular | extended)
adjustment *
enum(raw | split_adjusted)
from *
string:date-time
to *
string:date-time
bars *
array<BarItem>
nextCursor *
string
Opaque cursor for the next page, or null when this page is complete.
correlationId *
string:uuid
Request correlation ID.

200

A page of stored 5-minute bars for the ticker.

400

Invalid query (validation_failed, invalid_range, window_too_large, or invalid_cursor).

401

Missing or invalid access token.

403

Authenticated but not permitted.

404

Symbol was not found or is inactive.

500

Unexpected server failure.

503

Authorization service unavailable.

Operations2 endpoints
post/v1/stock-backfillsTrigger a historical stock backfill
Requires sign-in

Internal platform operations endpoint for historical bar imports. Fans out into independent ticker×month queue jobs on the shared backfill pool (same concurrency limit as nightly bar sync). Not an account-scoped tenant API. Authenticate with AuthKit; access currently requires the caller's WorkOS user id in `PLATFORM_ADMIN_USER_IDS`. Reports via `@providence/escalation` (no account audit logs).

Request bodyTriggerBackfillRequest
tickers *
array<string>
Tickers to backfill. Duplicates are ignored; values are uppercased.
from
string
Inclusive UTC start date. Defaults to six months before `to`.
to
string
Inclusive UTC end date. Defaults to yesterday UTC.
windowDays
integer
Provider fetch window size in days. Defaults to 5.
Response 202TriggerBackfillResponse
status *
enum(accepted)
tickers *
array<string>
from *
string
to *
string
windowDays *
integer
jobCount *
integer
Number of ticker×month queue jobs enqueued.
runIds *
array<string>
One backfill run TypeID per enqueued ticker×month job.
correlationId *
string:uuid
Request correlation ID.

202

Backfill jobs accepted (one runId per ticker×month slice).

400

Invalid backfill request.

401

Missing or invalid access token.

403

Authenticated but not permitted.

500

Unexpected server failure.

post/v1/stock-backfills/{runId}/retryRetry an existing historical stock backfill run
Requires sign-in

Internal platform operations endpoint. Re-enqueues one ticker×month `stock.backfill.requested` job for an existing `runId` (resumes pending/failed chunks, resets auto-requeue attempt to 1). AuthKit + `PLATFORM_ADMIN_USER_IDS`. Uses `@providence/escalation` only (no account audit logs).

Parameters
runId *pathExisting ticker×month backfill run TypeID to resume.
Response 202RetryBackfillResponse
runId *
string
Backfill run TypeID (`bfrun_…`).
status *
enum(accepted)
ticker *
string
from *
string
to *
string
windowDays *
integer
correlationId *
string:uuid
Request correlation ID.

202

Backfill retry accepted.

400

Run is not retryable or metadata is invalid.

401

Missing or invalid access token.

403

Authenticated but not permitted.

404

Backfill run not found.

500

Unexpected server failure.

Auth5 endpoints
post/v1/auth/magicStart Magic Auth email code login
Public

Public browserless AuthKit Magic Auth start. Always returns a uniform success body to avoid email enumeration.

Request bodyMagicAuthStartRequest
email *
string:email
ex. trader@example.com
Response 200MagicAuthStartResponse
status *
enum(code_sent)
correlationId *
string:uuid
Request correlation ID.

200

Magic Auth code send accepted (uniform response).

400

Invalid request body.

500

Unexpected server failure.

post/v1/auth/magic/verifyVerify Magic Auth code and establish a session
Public

Public Magic Auth verify. First-time users with zero WorkOS orgs must supply `accountName` to bootstrap a Providence account. Never returns org-less tokens.

Request bodyMagicAuthVerifyRequest
email *
string:email
code *
string
accountName
string
displayName
string
Response 200SessionAuthResponse
accessToken *
string
refreshToken *
string
expiresIn *
integer
userId *
string
User TypeID (`user_…`).
displayName *
string
accountId *
string
Account TypeID (`acct_…`).
workosOrganizationId *
string
correlationId *
string:uuid
Request correlation ID.

200

Org-scoped AuthKit session tokens.

400

Invalid request or first-account name required.

401

Missing or invalid access token.

409

Caller must select a WorkOS organization.

500

Unexpected server failure.

post/v1/auth/organizationComplete organization selection for a session
Public

Public. Completes a pending Magic Auth organization challenge or switches via refresh token.

Request bodySelectOrganizationRequest
organizationId *
string
pendingAuthenticationToken
string
refreshToken
string
Response 200SessionAuthResponse
accessToken *
string
refreshToken *
string
expiresIn *
integer
userId *
string
User TypeID (`user_…`).
displayName *
string
accountId *
string
Account TypeID (`acct_…`).
workosOrganizationId *
string
correlationId *
string:uuid
Request correlation ID.

200

Org-scoped AuthKit session tokens.

400

Invalid request body.

401

Missing or invalid access token.

500

Unexpected server failure.

post/v1/auth/tokenRefresh AuthKit session tokens
Public

Public. Rotates refresh tokens for the current organization context.

Request bodyRefreshTokenRequest
refreshToken *
string
Response 200SessionAuthResponse
accessToken *
string
refreshToken *
string
expiresIn *
integer
userId *
string
User TypeID (`user_…`).
displayName *
string
accountId *
string
Account TypeID (`acct_…`).
workosOrganizationId *
string
correlationId *
string:uuid
Request correlation ID.

200

Rotated org-scoped AuthKit session tokens.

400

Invalid request body.

401

Missing or invalid access token.

500

Unexpected server failure.

post/v1/auth/logoutRevoke an AuthKit session
Public

Public. Verifies the AuthKit access token (JWKS), then revokes the WorkOS session identified by the `sid` claim.

Request bodyLogoutRequest
accessToken *
string
Response 200LogoutResponse
status *
enum(revoked)
correlationId *
string:uuid
Request correlation ID.

200

Session revoked.

400

Access token missing a session id.

401

Missing or invalid access token.

500

Unexpected server failure.

Accounts2 endpoints
get/v1/accountsList accounts for the authenticated user
Requires sign-in

Returns the local membership projection for the AuthKit subject. Does not fan out to WorkOS.

Response 200ListAccountsResponse
accounts *
array<AccountSummary>
correlationId *
string:uuid
Request correlation ID.

200

Active account memberships for the caller.

401

Missing or invalid access token.

500

Unexpected server failure.

post/v1/accountsCreate an additional account and switch into it
Requires sign-in

Creates a new WorkOS organization + Providence account for the caller (max 5). Requires the current refresh token and returns switched org-scoped tokens for the new account. Preflight refresh may rotate the caller's token before provision; if create then fails, 401/500 responses include the rotated accessToken/refreshToken/expiresIn so clients can persist them.

Request bodyCreateAccountRequest
name *
string
refreshToken *
string
Response 201SessionAuthResponse
accessToken *
string
refreshToken *
string
expiresIn *
integer
userId *
string
User TypeID (`user_…`).
displayName *
string
accountId *
string
Account TypeID (`acct_…`).
workosOrganizationId *
string
correlationId *
string:uuid
Request correlation ID.

201

Account created; session switched to the new organization.

400

Invalid request body.

401

Missing/invalid access token, or WorkOS rejected credentials. May include rotated session tokens when preflight refresh succeeded before failure.

403

Account limit reached or caller cannot create.

500

Unexpected server failure. May include rotated session tokens when preflight refresh succeeded before failure.

Waitlist

Request access.