Skip to content
Trace Commons

Status and withdrawal

Read contributor status

Section titled “Read contributor status”

Status reads are scoped to identifiers the client already knows:

Terminal window
curl --fail-with-body \
  --request POST \
  --url https://ingest.tracecommons.ai/v1/contributors/me/submission-status \
  --header "authorization: Bearer $TRACE_COMMONS_UPLOAD_CLAIM" \
  --header "content-type: application/json" \
  --data '{"submission_ids":["<submission-id>"]}'

Unknown, cross-tenant, and cross-principal identifiers are omitted rather than distinguished. Clients should treat an omitted row as unavailable, not as proof that no trace exists.

The response can include current status, pending and final credit, delayed-credit ledger totals, safe explanations, and the recorded consent scopes. See What happens after submission for the full lifecycle.

Device-authenticated revocation

Section titled “Device-authenticated revocation”

The upload-claim API retains the device-authenticated revocation route for clients such as Ironclaw:

Terminal window
ironclaw traces revoke '<submission-id>' \
  --endpoint https://ingest.tracecommons.ai/v1/traces

This route is tenant- and contributor-scoped and uses the same upload-claim authorization family as submission.

Account-authenticated withdrawal

Section titled “Account-authenticated withdrawal”

The desktop app and contributor daemon use the account surface:

POST /v1/account/traces/{submission_id}/withdraw
Authorization: Bearer <short-lived-account-session-token>

Use the contributor client instead of hand-building the browser/loopback sign-in flow:

Terminal window
trace-commons-contributor account login
trace-commons-contributor daemon withdraw '<submission-id>'

Withdrawal is idempotent and account-scoped. It deletes stored content, evicts the trace from derived surfaces and future exports, and reports whether it had already been distributed. If it had appeared in a published export, copies already distributed cannot be recalled. Credit already recorded stays.

Stop versus revoke

Section titled “Stop versus revoke”
  • Opt out / disarm stops future automatic submission.
  • Revoke is the device-authenticated Trace Commons API action used by clients such as Ironclaw.
  • Withdraw is the account-authenticated contributor action exposed by the daemon and desktop apps.
  • Logout removes local identity and receipt state.

These are separate actions. A client should not imply that logging out or stopping the queue revokes prior contributions.