Public API

API overview

GET-only, read-only, workspace-scoped Public API for reports, Signals, accounts, stakeholders, website activity, and targeting summaries. Import this specification into an OpenAPI-compatible client, set the bearer API token supplied to your organization, and call the production HTTPS endpoint. The bearer token determines workspace scope.

Base URL: {See endpoint from your workspace}

Version: 1.2.0. Published endpoints: 11.

DOE API Token User Guide

DOE API tokens let approved clients access supported read-only Public API routes for a workspace. The token decides the workspace scope and must be sent as a standard bearer token.

Before you create a token

• Know which client or workflow will use the token.
• Know who owns that client or workflow.
• Decide whether the token should expire automatically.
• Decide where the token will be stored after creation.
• Create a separate token for each client or workflow.
• Do not reuse one token across unrelated consumers.
• Store the token in a password manager or secret manager immediately.

Quick start

1. Open the workspace that owns the API data.
2. Go to Settings.
3. Open API Tokens.
4. Click Generate token.
5. Confirm the Space ID.
6. Select API Space Read Only.
7. Review and copy the Public API endpoint shown in the dialog.
8. Choose an expiry date when the token should stop working automatically.
9. Click Generate.
10. Copy the token immediately from the success dialog and store it safely.

Safety checklist

• Create one token per client or workflow.
• Prefer expiring tokens unless there is a clear long-term need.
• Save the token immediately because the secret is shown only once.
• Store tokens in a secure secret manager or password manager.
• Rotate tokens when ownership changes or exposure is suspected.
• Revoke tokens you no longer need.
• Periodically review active tokens in the API Tokens table.

Reports

Read-only workspace reports.

curl "{See endpoint from your workspace}/api/v1/public/reports" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Signals

Read-only paginated workspace Signals with exact counts and compact references.

curl "{See endpoint from your workspace}/api/v1/public/signals" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Accounts

Read-only account listing and detail operations.

curl "{See endpoint from your workspace}/api/v1/public/accounts" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

curl "{See endpoint from your workspace}/api/v1/public/accounts/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Stakeholders

Read-only stakeholder listing and detail operations.

curl "{See endpoint from your workspace}/api/v1/public/stakeholders" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

curl "{See endpoint from your workspace}/api/v1/public/stakeholders/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Website

Read-only website visits, journeys, top pages, and aggregate insights.

curl "{See endpoint from your workspace}/api/v1/public/website/visits" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

curl "{See endpoint from your workspace}/api/v1/public/website/accounts" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

curl "{See endpoint from your workspace}/api/v1/public/website/top-pages" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

curl "{See endpoint from your workspace}/api/v1/public/website/insights" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Targeting

Read-only workspace targeting summary.

curl "{See endpoint from your workspace}/api/v1/public/targeting-summary" \
  -H "Authorization: Bearer $DOE_API_TOKEN" \
  -H "Accept: application/json"

{
  "message": "Successful response"
}

Frequently asked questions

I closed the success dialog without copying the token. Can I get it back?

No. The secret token value is shown only once. Create a new token or rotate the existing one if you still need access.

Which endpoint should I use?

The generate dialog shows this URL when the API profile is selected.

Where can I review the available APIs?

Use the API guide on this page. It groups supported Public API endpoints by product area and shows parameters, request examples, and response shapes without needing separate files.

Which header should I send?

Use Authorization: Bearer <token>. This is the supported authentication header for API tokens.

What can the read-only API token access?

It can call supported routes under /api/v1/public for the workspace that issued the token. It does not create, edit, delete, or approve workspace data.

How should I page through long result sets?

Use the documented take and skip query parameters where they are available. Keep pages small, process one page at a time, and avoid running large reporting jobs in a tight loop.

How do I handle a 429 rate-limit response?

Read the Retry-After header, wait for that duration, and retry with lower request volume. For scheduled jobs, spread calls over time instead of starting every report at once.

Can I use X-MCP-Token or ?token= with an API token?

No. Those carriers are not supported for the API Space Read Only profile. Use the standard Authorization bearer header instead.

Can one token be shared by multiple tools?

Avoid sharing one token across unrelated tools. Create one token per client or workflow so ownership, rotation, expiry, and troubleshooting stay clear.

What is the difference between rotate and revoke?

Rotate replaces the secret with a new one so the client can continue after you update it. Revoke disables the token completely.

What happens when a token expires?

An expired token should no longer authenticate. If the client still needs access, create a new token or rotate the existing one with a new expiry.

When should I leave expiry empty?

Only for a stable long-term workflow with known ownership, secure storage, and a real review process. If you are unsure, do not leave it empty.

What should I include when asking for support?

Share the route, method, approximate time, response code, and X-Request-Id if available. Do not send the full bearer token, screenshots containing secrets, or copied Authorization headers.