API reference

Access and authentication

API access is available on active Pro, Business, and Enterprise plans. Open Account in the dashboard, create a named API key, and copy it immediately—the complete key is shown only once. Send the key as a Bearer token over HTTPS.

Authorization: Bearer tg_live_your_key
X-Workspace-Id: ws_your_workspace_id

API keys belong to the user who created them rather than to a single workspace. Each request is authorized against that user's workspace access.

The public API base URL is https://tracegraphs.com/api/v1. Append the endpoint path shown below—for example, the signals URL is https://tracegraphs.com/api/v1/signals. Do not use https://tracegraphs.com/api/backend; that path is the dashboard's session-authenticated internal proxy and will reject API-key-only requests. Never expose an API key in browser code, source control, or logs.

Workspace scope

Customer-facing reads and writes are scoped by the X-Workspace-Id header. The equivalent workspace_id query parameter is also accepted; when both are supplied, the header takes precedence. Use GET /workspacesto discover available IDs. If neither is supplied, the API selects the user's oldest personal workspace, normally Personal Workspace. It does not default to Global.

The reserved global workspace exposes shared, globally visible intelligence. Personal and team workspaces include only their selected articles and reachable claims, entities, companies, insights, and weights. An inaccessible or nonexistent workspace returns 404 without revealing whether another user owns it.

Example request

curl "https://tracegraphs.com/api/v1/signals?direction=negative&limit=25" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "X-Workspace-Id: $TRACEGRAPHS_WORKSPACE_ID" \
  -H "Accept: application/json"

Successful list requests normally return JSON arrays. Endpoints that accept include_total=true return {"items": [...], "total": 123}instead. Errors return an HTTP status and a JSON detail message. A revoked, inactive, or invalid key returns 401; exceeding a rate or usage limit returns 429.

Rate and usage limits

API traffic uses a Redis-backed token bucket. Pro includes 120 API units per minute, Business includes 600, and Enterprise limits are configured for the account. Capacity refills continuously instead of resetting at the start of each minute.

• GET, HEAD, and OPTIONS requests cost 1 unit.
• Submitting an article costs 5 units.
• Running a discovery search request costs 10 units.
• Other workspace and discovery-agent mutations cost 3 units.
• A 429 response includes Retry-After; wait that many seconds before retrying.

Per-minute API limits are separate from monthly article-processing and discovery-search allowances. All API keys owned by one user share that user's limit.

Workspace management

List the Global workspace and every workspace accessible to the API-key owner:

curl "https://tracegraphs.com/api/v1/workspaces" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY"

Results include id, name, kind, your role, graph shard, creation time, and article count. Workspace creation is limited by the active subscription plan.

• Basic includes Global plus 1 personal workspace, but external API access begins on Pro.
• Pro supports up to 3 personal or team workspaces, 10 Monitors, and 1 Research Agent.
• Business supports up to 10 personal or team workspaces, 50 Monitors, and 5 Research Agents.
• Enterprise limits are configured for the account.

curl -X POST "https://tracegraphs.com/api/v1/workspaces" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supply Chain Research"}'

Only an owner can delete a workspace. Deletion removes the workspace selection, disables and unbinds its discovery agents, and does not delete shared articles, claims, or entities from the canonical graph.

curl -X DELETE "https://tracegraphs.com/api/v1/workspaces/$TRACEGRAPHS_WORKSPACE_ID" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY"

Endpoints

OpenAPI schema

Authenticated integrations can download the current machine-readable schema from GET /openapi.json. The schema uses backend-relative paths; prefix them with https://tracegraphs.com/api/v1 for customer requests. The same API-key authentication and plan requirements apply.

curl "https://tracegraphs.com/api/v1/openapi.json" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -o tracegraphs-openapi.json

Reading data

• List endpoints accept limit and offset; subjects, companies, signals, entities, articles, and article jobs support include_total=true.
• Companies accepts search, ticker_only, sector, exchange, country, sort, and order.
• The /signals endpoint accepts company, watchlist_id, direction, method, search, min_score, sort, order, and time-influence parameters.
• The company insights endpoint accepts direction, method, limit, offset, and time-influence parameters.
• Entity weights accepts kind, direction, search, sort, order, limit, offset, and time-influence parameters.
• Keywords accepts period_days, search, keyword_type, direction, min_articles, sort, order, limit, and offset.

Direction is all, positive, or negative. Method is company_direct_impact or company_market_exposure. Limits range from 1 to 200 and default to 50.

Governed markets

Use GET /subjects to search the governed catalog used by watchlists, Monitors, and Research Agents. Article processing cannot create these records. Supported subject types are issuer, security, commodity, etf, index, currency, cryptocurrency, and topic.

• search matches canonical names, symbols, and governed aliases.
• subject_type restricts results to one governed asset class.
• is_tradable=true or false filters market instruments versus research-only subjects.
• sort accepts relevance, subject, type, market, industry, symbol, or exchange.
• order accepts asc or desc; limit is 1–200 and offset is zero-based.
• include_total=true returns an items/total page object for stable pagination.

curl "https://tracegraphs.com/api/v1/subjects?search=ETH&subject_type=cryptocurrency&sort=relevance&limit=20&offset=0&include_total=true" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY"

Subject IDs contain provider-neutral and provider-specific characters. URL-encode the complete ID when requesting GET /subjects/{id} or removing a watchlist item.

Watchlists

Watchlists belong to the selected personal or team workspace. New users receive a default watchlist. Adding an item requires a subject ID returned by GET /subjects; arbitrary names and article-extracted companies are rejected.

curl -X POST "https://tracegraphs.com/api/v1/watchlists/$WATCHLIST_ID/items" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "X-Workspace-Id: $TRACEGRAPHS_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"subject_id":"massive:cryptocurrency:eth","notes":"Core digital-assets coverage"}'

Per-watchlist item caps follow the account plan. Watchlists organize subjects but do not schedule work by themselves; target one from a Monitor or Research Agent.

Pass watchlist_id to GET /signals to return only insights connected to subjects in that watchlist. Matching uses governed IDs, company symbols and names, and signal contexts such as commodities or markets.

Time influence parameters

• time_mode=decay uses half_life_days to reduce the influence of older evidence.
• time_mode=range uses date_from and date_to in YYYY-MM-DD format.
• time_mode=all_time includes all available evidence without age-based decay.

Create requests

Submit one article URL to a personal or team workspace. Direct URLs cannot be submitted while scoped to Global; use discovery searches in Global instead.

curl -X POST "https://tracegraphs.com/api/v1/articles/enqueue" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "X-Workspace-Id: $TRACEGRAPHS_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report"}'

Run discovery for up to 10 queries:

curl -X POST "https://tracegraphs.com/api/v1/searches" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "X-Workspace-Id: $TRACEGRAPHS_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "queries":["semiconductor export controls"],
    "max_urls_per_query":10
  }'

Each processed article and discovery query counts toward your plan's monthly usage. max_urls_per_query accepts values from 1 to 50. Duplicate articles are reported but are not queued again. Results from a personal or team search are associated with that workspace; Global searches contribute globally visible discoveries.

Discovery agents

Monitoring and Research Agents use the same scheduling API but remain distinct product concepts. Set automation_type to monitor for deterministic recurring searches or research for LLM-planned adaptive investigation. Agents must be assigned to a personal or team workspace and cannot target Global. The API-key owner must have an owner or admin workspace role to create or delete agents.

curl -X POST "https://tracegraphs.com/api/v1/workspaces/$TRACEGRAPHS_WORKSPACE_ID/agents" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Semiconductor monitor",
    "automation_type":"monitor",
    "instructions":"Find material semiconductor supply-chain developments.",
    "target_mode":"subject",
    "target_subject_ids":["company:cik_0000320193"],
    "schedule_kind":"weekdays",
    "schedule_time":"08:00",
    "schedule_weekdays":[1,2,3,4,5],
    "schedule_timezone":"America/New_York",
    "max_articles_per_run":10
  }'

• GET /workspaces/agents/all lists every discovery agent owned by the authenticated user, including its workspace name.
• POST /workspaces/agents/all accepts the same fields plus workspace_id; PUT /workspaces/agents/all/{agent_id} updates an owned automation.
• target_mode accepts watchlist, subject, topic, or mixed; use watchlist_id and/or target_subject_ids as appropriate.
• Schedules support daily, weekdays, weekly, or the legacy interval mode; schedule times use the supplied IANA timezone.
• schedule_minutes ranges from 60 to 10,080 minutes when schedule_kind=interval.
• max_articles_per_run ranges from 1 to 100.
• Deleting a workspace disables and unbinds every agent assigned to it.

Key management

• Use a separate named key for each integration or environment.
• Store keys in a secret manager or protected environment variable.
• Revoke a key from Account as soon as it is no longer needed or may have been exposed.
• Key creation and revocation take effect without changing your dashboard password.