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.

Use the API base URL provided for your TraceGraphs environment. Do not use the dashboard's internal /api/backend path in external integrations, and 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://<your-api-host>/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 return JSON arrays. 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://<your-api-host>/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 and 1 discovery agent.
• Business supports up to 10 personal or team workspaces and 5 discovery agents.
• Enterprise limits are configured for the account.

curl -X POST "https://<your-api-host>/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://<your-api-host>/workspaces/$TRACEGRAPHS_WORKSPACE_ID" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY"

Endpoints

Reading data

• List endpoints accept limit; article lists and jobs also accept offset and status.
• Companies accepts search and limit.
• The /signals endpoint accepts company, direction, method, limit, and time-influence parameters.
• The company insights endpoint accepts direction, method, limit, and time-influence parameters.
• Entity weights accepts kind, direction, limit, and time-influence parameters.

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.

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://<your-api-host>/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://<your-api-host>/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

Discovery agents are available according to plan and must be assigned to a personal or team workspace. They cannot be assigned to Global. The API-key owner must have an owner or admin workspace role to create or delete agents through workspace routes.

curl -X POST "https://<your-api-host>/workspaces/$TRACEGRAPHS_WORKSPACE_ID/agents" \
  -H "Authorization: Bearer $TRACEGRAPHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Semiconductor monitor",
    "instructions":"Find material semiconductor supply-chain developments.",
    "topics":["semiconductors","export controls"],
    "schedule_minutes":360,
    "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 agent fields plus workspace_id.
• schedule_minutes ranges from 60 to 10,080 minutes.
• 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.