Read your portfolio with an agent.

1. Sign in to the workspace as its owner. Open Settings, then Organization → API tokens, or open API tokens directly.
2. Enter a required Name, up to 80 characters, such as codex-read. Leave Scope at its default, read.
3. Choose Mint token, then Copy to clipboard. The plaintext appears once. Only its hash is stored, so you cannot retrieve the token later.
4. Keep it in your secret manager or private terminal. Run the Bash block below and enter the token at the hidden prompt. Never paste it into this public page, a URL, a shared chat, a log, or a command saved in shell history.

set +x
IFS= read -r -s -p 'OXbeat read token: ' OXBEAT_READ_TOKEN
printf '\n'
export OXBEAT_READ_TOKEN

This guide uses read scope only. Fleet write tokens add annotations to existing flags; they do not dispatch actions into your apps. Older token-screen copy may call this the Agent plan or mention dispatch.

Use the same private Bash session. This authenticated GET returns markdown, with the same renderer used for the email digest. The token travels in an authorization header, never in the URL.

(
  set +x
  : "${OXBEAT_READ_TOKEN:?Load OXBEAT_READ_TOKEN first}"
  if [[ ! "$OXBEAT_READ_TOKEN" =~ ^[A-Za-z0-9_-]+$ ]]; then
    printf 'Invalid token format. Copy the token again.\n' >&2
    exit 1
  fi
  if ! result=$(printf 'header = "Authorization: Bearer %s"\n' "$OXBEAT_READ_TOKEN" |
    curl --disable --silent --config - --connect-timeout 5 --max-time 15 \
      --max-filesize 1048576 --write-out '\n%{http_code} %{content_type}' \
      'https://app.oxbeat.ai/api/v1/digest/latest?format=md'); then
    printf 'Network read failed. Check the connection and retry.\n' >&2
    exit 1
  fi
  metadata=${result##*$'\n'}
  body=${result%$'\n'*}
  case "$metadata" in
    '200 text/markdown'*)
      [[ -n "$body" ]] || { printf 'Expected markdown, got an empty response.\n' >&2; exit 1; }
      printf '%s\n' "$body" ;;
    '200 '*) printf 'Expected markdown. Check the endpoint and retry.\n' >&2; exit 1 ;;
    '401 '*) printf '401: token missing, invalid or revoked. Check API tokens.\n' >&2; exit 1 ;;
    '403 '*) printf '403: unexpected for this read. Check the URL and contact support.\n' >&2; exit 1 ;;
    '404 '*) printf '404: no built digest yet. A snapshot sync does not build one; wait for the scheduled digest.\n' >&2; exit 1 ;;
    *) printf 'Read failed. Check the endpoint or retry later.\n' >&2; exit 1 ;;
  esac
)

Copy REST read

Latest means the latest built digest, not the latest metric snapshot. Before the first build, a 404 with no digest found is normal. Sync now defaults to a snapshot-only sync and does not create a digest. Wait for the scheduled built digest, or inspect existing dashboard and source metrics. A read token cannot trigger a sync or build.

Want to inspect the format first? Open the synthetic public digest. It uses example data and requires no token.

For Codex CLI 0.160.0, register the Streamable HTTP server locally. Review the command before running it: it adds an oxbeat entry to your Codex MCP configuration, storing the environment variable name rather than your token.

(
  set +x
  : "${OXBEAT_READ_TOKEN:?Load OXBEAT_READ_TOKEN first}"
  codex mcp add oxbeat \
    --url https://app.oxbeat.ai/api/mcp/mcp \
    --bearer-token-env-var OXBEAT_READ_TOKEN
)

Copy Codex registration

Start Codex from a shell with OXBEAT_READ_TOKEN exported. Ask it to call get_latest_digest and get_flags. Both read the latest built digest. If your client lacks Streamable HTTP support, use the REST read above.

Use --bearer-token-env-var for HTTP. Codex's --env option applies to stdio servers. This page copies commands only; it never registers a server or reads your private endpoints.

Give your agent this reading instruction:

Read the digest date, built timestamp, sync status and configured source coverage before making claims. Report active red flags as attention items and active yellow flags as watch items. Exclude snoozed flags from attention, but retain known source warnings when stating confidence.

• For each flag, inspect appId, rule, level, lifecycle status and evidence: metric, observed value, baseline, threshold and direction. Use list_rules to understand the rule and its first investigation step.
• For JSON reads, digest/latest returns a digest row with the structured digest under payload; flags also appear at the top level. Prefer source-qualified payload metrics over a legacy generic aggregate zero.
• Missing, stale or unavailable sources limit confidence. An empty flags array does not prove complete coverage or that every source is healthy.
• Describe what the evidence supports. An annotation records an investigation note; it does not fix the underlying app.

401 / Missing, invalid or revoked token

Check that the environment variable is available in the client process. If the token is lost or revoked, mint a replacement as the workspace owner. Never share the old token while asking for help. A read-scoped token used on the write endpoint also receives 401.

403 / Check the operation

The latest digest read has no paid-access gate. On POST /api/v1/flags/annotate, plan_required means the workspace lacks Fleet write access, after write-scope authentication succeeds. A 403 on the GET above is unexpected: confirm the URL, then contact support with the status and operation only.

404 / No built digest found

Wait for a scheduled built digest or inspect existing dashboard and source metrics. A snapshot-only manual sync can succeed while this endpoint still has no digest.

Network, service or unexpected response

Retry the read when your connection recovers. Use REST if MCP setup is unavailable. Do not interpret a failed response as zero users, zero revenue or no flags.

Revoke or disconnect

Open Settings → Organization → API tokens. Find the named token, select Revoke, and confirm the message that clients using it will stop working. Revocation applies to subsequent authenticated requests. Replace the token in affected clients and clear your shell variable with unset OXBEAT_READ_TOKEN when finished.

To remove the local Codex registration, run codex mcp remove oxbeat. Removing the registration or clearing the variable does not revoke the token; revoke it in OXbeat if it was exposed.

This public reference describes OXbeat's read contract. It contains no workspace data and needs no token.

Loading public documentation.

Read the public documentation directly at https://oxbeat.ai/llms.txt

Read /llms.txt directly