Ops

Operator routes: imports, operators, drafts and their approval, retractions, the audit log. Every call needs an operator credential and is audited.

Generated from openapi.yaml (Btcintel native API 0.1.0). Every hash is canonical display order; every answer carries the index and node heights; errors use one envelope — see Semantics.

GET /v1/ops/operators — Operators (ops)
POST /v1/ops/operators — Create or replace an operator (human admin)
PATCH /v1/ops/operators/{id} — Change roles, budget or the kill switch (human admin)
GET /v1/ops/drafts — Drafts awaiting or past decision (ops)
POST /v1/ops/drafts — Propose a claim, entity, relation or event (ops; the gate of P42)
GET /v1/ops/drafts.csv — The drafts to sample for a batch, as CSV (human curator or admin)
GET /v1/ops/operators/{id}/record — An operator's drafts per source over a window (human curator or admin)
POST /v1/ops/drafts/batch — Approve a batch of drafts after reviewing a sample (human curator or admin)
POST /v1/ops/drafts/{id}/approve — Approve a draft (human curator or admin, never its proposer)
POST /v1/ops/drafts/{id}/reject — Reject a draft with a reason (human curator or admin)
POST /v1/ops/claims/{claim_id}/retract — Retract a claim with a reason (human curator or admin)
POST /v1/ops/campaigns/{claim_id}/promote — Promote a source's provisional members of a campaign (human curator or admin)
POST /v1/ops/claims/{claim_id}/release — Release one campaign member that waits for a review (human curator or admin)
POST /v1/ops/claims/{claim_id}/reject — Reject one campaign member that waits for a review (human curator or admin)
GET /v1/ops/disputes — The dispute queue (ops)
POST /v1/ops/disputes/{id}/resolve — Resolve a dispute (human curator or admin)
GET /v1/ops/audit — The audit log (ops), paginated by id
GET /v1/ops/relay/policy — The relay's write policy (ops)
PATCH /v1/ops/relay/policy — Change the relay's write policy (ops, human admin)
GET /v1/ops/community/moderation — The moderation trail (ops), newest first
POST /v1/ops/community/moderation — Hide or unhide an event, ban or unban a pubkey (ops, human admin or moderator)
GET /v1/ops/community/labelers — The labeler directory, listed or not (ops)
POST /v1/ops/community/labelers — Add a labeler to the directory (ops, human admin or curator)
PATCH /v1/ops/community/labelers/{pubkey} — Change a labeler's directory entry (ops, human admin or curator)
POST /v1/sources/{id}/import — Push a source file through its parser (ops)
GET /v1/ops/imports/{id} — One import run (ops)

GET `/v1/ops/operators`

Operators (ops)

Auth: An operator credential as the bearer; every call is audited.

Response `200`

Every operator, human or agent.

schema

items array of Operator
- id string
- kind string · one of "human", "agent"
- display_name string
- roles array of string
- daily_action_budget integer | null
- active boolean
- created_at string (date-time)

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/operators \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/operators`

Create or replace an operator (human admin)

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

id string required
kind string required · one of "human", "agent"
display_name string
roles array of string
daily_action_budget integer — Required for agents (P46).
active boolean

Response `201`

The operator.

schema

id string
kind string · one of "human", "agent"
display_name string
roles array of string
daily_action_budget integer | null
active boolean
created_at string (date-time)

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/operators \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"id":"…","kind":"human"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

PATCH `/v1/ops/operators/{id}`

Change roles, budget or the kill switch (human admin)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	string	—

Request body

schema

roles array of string
daily_action_budget integer
active boolean — false switches the operator off everywhere (403).
display_name string

Response `200`

The operator after the change.

schema

id string
kind string · one of "human", "agent"
display_name string
roles array of string
daily_action_budget integer | null
active boolean
created_at string (date-time)

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X PATCH https://api.btcintel.io/v1/ops/operators/1 \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/drafts`

Drafts awaiting or past decision (ops)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`status`	query	string · one of "draft", "approved", "rejected", "withdrawn"	—
`limit`	query	integer · ≤ 500 · default 100	—

Response `200`

Drafts, newest first.

schema

items array of Draft
- id integer
- claim_table string
- payload object
- proposed_by string
- source_id string | null
- lead_event_id string | null
- status string · one of "draft", "approved", "rejected", "withdrawn"
- decided_by string | null
- decided_at string | null (date-time)
- reason string | null
- published_id integer | null
- created_at string (date-time)

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/drafts \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/drafts`

Propose a claim, entity, relation or event (ops; the gate of P42)

An agent's writes always become drafts; a human's proposal waits for a different human too. Approval publishes through the writer under the draft's source.

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

claim_table string required · one of "intel.annotations", "intel.entities", "intel.entity_relations", "intel.events"
payload object required — ClaimInput {subject_kind, subject_key, label, category|abuse, entity_id, role, method, confidence_class, evidence}, EntityInput {id, name, kind, …}, RelationInput {from_entity, to_entity, type, …} or EventInput {kind, occurred_at, title, cites, subjects, entities}.
source_id string
lead_event_id string — 32-byte Community event id in hex.

Response `201`

The draft.

schema

id integer
claim_table string
payload object
proposed_by string
source_id string | null
lead_event_id string | null
status string · one of "draft", "approved", "rejected", "withdrawn"
decided_by string | null
decided_at string | null (date-time)
reason string | null
published_id integer | null
created_at string (date-time)

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/drafts \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"claim_table":"intel.annotations","payload":{}}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/drafts.csv`

The drafts to sample for a batch, as CSV (human curator or admin)

Spec S7.3 FR-3. One row per draft, newest first, at most 500: id, created, status, proposer, source, claim table, subject, label, category, abuse word, the cited URLs, and the guard that would hold a pending draft out of a batch (empty when none). A cell a spreadsheet would read as a formula starts with an apostrophe.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`status`	query	string · one of "draft", "approved", "rejected", "withdrawn"	—
`proposed_by`	query	string	An operator id, e.g. agent:grok-bot.
`source_id`	query	string	—
`limit`	query	integer · ≥ 1 · ≤ 500 · default 500	—

Response `200`

The drafts.

schema

string

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/drafts.csv \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/operators/{id}/record`

An operator's drafts per source over a window (human curator or admin)

Spec S7.3 FR-4. Per source: the drafts the operator proposed in the window, by their status now, and the disputes resolved in the window against claims published from them, upheld and partly upheld. Counts only: nothing is rated or ranked. It is the data behind a decision to widen an agent's autonomy for a source (P77).

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	string	—
`days`	query	integer · ≥ 1 · ≤ 90 · default 28	—

Response `200`

The record.

schema

operator_id string required
days integer required
since string (date-time) required
sources array of object required
- source_id string — Absent for the drafts proposed without a source.
- proposed integer required
- approved integer required
- rejected integer required
- pending integer required
- withdrawn integer required
- disputes_upheld integer required
- disputes_partly_upheld integer required

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.

Example

curl -s https://api.btcintel.io/v1/ops/operators/1/record \
  -H 'Authorization: Bearer $BTCI_KEY' | jq '{operator_id, days, since}'

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/drafts/batch`

Approve a batch of drafts after reviewing a sample (human curator or admin)

Spec S7.3 FR-1 and FR-2 (P77). The batch holds 1 to 500 drafts, every one still a draft, none proposed by the reviewer. reviewed lists the sample the reviewer checked: at least 25 drafts of the batch, or all of them when it holds fewer. A draft a guard holds stays a draft for its own decision: a subject another source names as a service (collision), an abuse word no other source gives the subject (single_source), a chain fact that does not match (chain_mismatch). The other drafts are published one by one with the reviewer as actor; a failure stops the batch at stopped_at. One draft_batch audit row records the batch, the sample and the note.

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

draft_ids array of integer required
reviewed array of integer required — The sample the reviewer checked; part of draft_ids.
note string required — What the reviewer checked.

Response `200`

What was approved, what a guard held and, on a failure, where the batch stopped.

schema

approved array of object required
- draft_id integer required
- claim_id string — ann_<n> for an annotation draft.
held array of object required
- draft_id integer required
- reason string required
stopped_at object
- draft_id integer
- error string

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — A draft of the batch was decided already (conflict, naming them).
422 — A draft of the batch has no source to publish under.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/drafts/batch \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"draft_ids":[],"reviewed":[],"note":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/drafts/{id}/approve`

Approve a draft (human curator or admin, never its proposer)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Response `200`

The draft with its published id.

schema

id integer
claim_table string
payload object
proposed_by string
source_id string | null
lead_event_id string | null
status string · one of "draft", "approved", "rejected", "withdrawn"
decided_by string | null
decided_at string | null (date-time)
reason string | null
published_id integer | null
created_at string (date-time)

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — The draft was decided already.
422 — The payload could not be published (the message says why).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/drafts/1/approve \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/drafts/{id}/reject`

Reject a draft with a reason (human curator or admin)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Request body

schema

reason string required

Response `200`

The rejected draft.

schema

id integer
claim_table string
payload object
proposed_by string
source_id string | null
lead_event_id string | null
status string · one of "draft", "approved", "rejected", "withdrawn"
decided_by string | null
decided_at string | null (date-time)
reason string | null
published_id integer | null
created_at string (date-time)

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/drafts/1/reject \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/claims/{claim_id}/retract`

Retract a claim with a reason (human curator or admin)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`claim_id` required	path	string	—

Request body

schema

reason string required

Response `200`

Retracted; the claim stays addressable at its versions.

schema

retracted string
reason string

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/claims/ann_33932/retract \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/campaigns/{claim_id}/promote`

Promote a source's provisional members of a campaign (human curator or admin)

Spec S1.11 FR-8 (P42). Every provisional member the source names in the campaign becomes current, announced on the change feed, once a human has reviewed a sample: reviewed names at least 25 of the batch's members, or all of them when there are fewer, and only members of the batch (400 otherwise). The review counts for FR-10 too. Held members stay held: they are released one by one. One audit entry records the sample and the note. An agent gets 403.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`claim_id` required	path	string	The campaign, evt_<n>.

Request body

schema

source_id string required
reviewed array of string required
note string

Response `200`

The batch is current.

schema

campaign string
source_id string
promoted integer

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — No member of that source waits for a review in the campaign (conflict).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/campaigns/ann_33932/promote \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source_id":"…","reviewed":[]}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/claims/{claim_id}/release`

Release one campaign member that waits for a review (human curator or admin)

Spec S1.11 FR-8, FR-9. A provisional or held member becomes current, announced on the change feed; audited with the note. An agent gets 403.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`claim_id` required	path	string	—

Request body

schema

note string

Response `200`

The member, current.

schema

Claim — An annotation (CC-4): what a named source says about a subject, with citation. Never a score. Its fetch is the fetch that first stated the claim's current content, the one content_sha256 covers (CC-5, P74); a later fetch that restates it moves last_seen, never the version.

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
409 — The claim is not a campaign member waiting for a review (conflict).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/claims/ann_33932/release \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/claims/{claim_id}/reject`

Reject one campaign member that waits for a review (human curator or admin)

Spec S1.11 FR-8, FR-9. A provisional or held member becomes rejected with the reason: kept for the record, served to operators only, never on the change feed. Audited. An agent gets 403.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`claim_id` required	path	string	—

Request body

schema

reason string required

Response `200`

The member, rejected.

schema

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
409 — The claim is not a campaign member waiting for a review (conflict).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/claims/ann_33932/reject \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/disputes`

The dispute queue (ops)

Spec S5.3 FR-2. Every dispute with the opener and the text, newest first; status filters; cursor pagination by id.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`status`	query	string · one of "open", "resolved", "withdrawn"	—
`cursor`	query	integer	—
`limit`	query	integer · ≤ 500 · default 50	—

Response `200`

The queue.

schema

items array of OpsDispute required
next_cursor integer | null

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).

Example

curl -s https://api.btcintel.io/v1/ops/disputes \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/disputes/{id}/resolve`

Resolve a dispute (human curator or admin)

Spec S5.3 FR-2 (P8, P9, P42). The outcome and the resolver's public note, plus an optional action on the Curated side, run under the operator as actor and audited: retract (any claim kind, with a reason), expire (annotations, attributions and relations, with valid_to) or new_version (a correction of an annotation from a ClaimInput patch — label, category, abuse, concepts, role, evidence — recorded as a new version of the same claim with a new content hash, P32; the source, the subject and the confidence class stay). An agent operator cannot resolve: it proposes a resolution as a draft.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Request body

schema

outcome string required · one of "upheld", "rejected", "partially_upheld"
note string · max length 4096
action object
- retract object
  - reason string required
- expire object
  - valid_to string (date-time) required
- new_version object — A ClaimInput patch (label, category, abuse, concepts, role, evidence, first_reported_at); annotations only; the subject and the source never change.

Response `200`

Resolved; the action's effect is on the claim.

schema

OpsDispute

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — The state refuses the change (conflict): an open dispute by this caller exists already, or the dispute or claim is not open any more.
422 — Malformed input (bad hex, wrong-network address, bad vout).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/disputes/1/resolve \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"outcome":"upheld"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/audit`

The audit log (ops), paginated by id

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`since`	query	integer	Return rows with id greater than this.
`actor`	query	string	—
`table`	query	string	—
`limit`	query	integer · ≤ 1000 · default 100	—

Response `200`

Audit rows.

schema

items array of AuditEntry
- id integer
- at string (date-time)
- actor string
- action string
- table string
- row_id string
- details object
next_cursor integer | null

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/audit \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/relay/policy`

The relay's write policy (ops)

Spec S4.1 FR-2, FR-8: write_enabled (false until S4.4 signs the posting policy off, P37), min_pow_difficulty, attack_mode (raises the effective floor to 24 bits, P23) and who changed it last.

Auth: An operator credential as the bearer; every call is audited.

Response `200`

The policy row.

schema

write_enabled boolean required — False until the posting policy is signed off (S4.4, P37).
min_pow_difficulty integer required · ≥ 0 · ≤ 64
attack_mode boolean required — Raises the effective floor to 24 bits (P23).
floor integer required — The effective minimum difficulty the door enforces.
moderation_reasons array of string — Spec S4.4 FR-4: the vocabulary a moderation reason must come from; legal:<reference> and other:<text> are always accepted.
updated_at string (date-time) required
updated_by string | null — operator:<id> of the last change.

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/relay/policy \
  -H 'Authorization: Bearer $BTCI_KEY' | jq '{write_enabled, min_pow_difficulty, attack_mode}'

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

PATCH `/v1/ops/relay/policy`

Change the relay's write policy (ops, human admin)

Spec S4.1 FR-2, FR-8: any subset of write_enabled, min_pow_difficulty (0–64) and attack_mode. The relay applies the change at once; the change is audited under access.relay_policy.

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

write_enabled boolean
min_pow_difficulty integer · ≥ 0 · ≤ 64
attack_mode boolean
moderation_reasons array of string

Response `200`

The policy after the change.

schema

write_enabled boolean required — False until the posting policy is signed off (S4.4, P37).
min_pow_difficulty integer required · ≥ 0 · ≤ 64
attack_mode boolean required — Raises the effective floor to 24 bits (P23).
floor integer required — The effective minimum difficulty the door enforces.
moderation_reasons array of string — Spec S4.4 FR-4: the vocabulary a moderation reason must come from; legal:<reference> and other:<text> are always accepted.
updated_at string (date-time) required
updated_by string | null — operator:<id> of the last change.

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X PATCH https://api.btcintel.io/v1/ops/relay/policy \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/community/moderation`

The moderation trail (ops), newest first

Spec S4.1 FR-9: the append-only lens trail, paged by id (cursor = the id to continue below).

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`cursor`	query	integer	Return rows with an id below this.
`limit`	query	integer · ≤ 200 · default 50	—

Response `200`

A page of the trail.

schema

items array of Moderation required
- id integer required
- action string required · one of "hide", "unhide", "ban", "unban"
- event_id string — 64 hex characters (hide/unhide).
- pubkey string — 64 hex characters (ban/unban).
- npub string | null
- reason string required
- actor string required — operator:<id>.
- at string (date-time) required
next_cursor integer | null required — The cursor for the next page; null on the last one.

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/community/moderation \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/community/moderation`

Hide or unhide an event, ban or unban a pubkey (ops, human admin or moderator)

Spec S4.1 FR-9 (P25): appends a row to the lens and applies it — hidden events and banned pubkeys' events leave every public read and the relay at once; nothing is deleted. Ids may be 64 hex characters or NIP-19 (note1…, npub1…). A pubkey never seen can be banned ahead of its first event. S4.4 fixes the vocabulary of reasons.

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

action string required · one of "hide", "unhide", "ban", "unban"
event_id string — The event to hide or unhide (64 hex or note1…).
pubkey string — The pubkey to ban or unban (64 hex or npub1…).
reason string required — One of the policy's moderation_reasons, or legal:<reference>, or other:<text> (S4.4 FR-4). · max length 500

Response `201`

The row appended.

schema

id integer required
action string required · one of "hide", "unhide", "ban", "unban"
event_id string — 64 hex characters (hide/unhide).
pubkey string — 64 hex characters (ban/unban).
npub string | null
reason string required
actor string required — operator:<id>.
at string (date-time) required

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — No such event, or an unban of a pubkey that is not banned (not_found).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/community/moderation \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"action":"hide","reason":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/community/labelers`

The labeler directory, listed or not (ops)

Spec S4.1 FR-10 (P28): every labeler in the directory; the public list (S4.2) shows the listed ones only.

Auth: An operator credential as the bearer; every call is audited.

Response `200`

The directory.

schema

items array of Labeler required
- pubkey string required
- npub string | null
- name string required
- namespace string required — io.btcintel (P22).
- description string | null
- url string | null (uri)
- criteria_url string | null (uri) — Where the labeler explains its criteria (P28).
- listed boolean required — Shown in the public directory (S4.2).
- added_by string | null
- added_at string (date-time) required

Errors

401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).

Example

curl -s https://api.btcintel.io/v1/ops/community/labelers \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/ops/community/labelers`

Add a labeler to the directory (ops, human admin or curator)

Spec S4.1 FR-10 (P28): a labeler is a pubkey whose NIP-32 labels readers may choose as a lens. Unlisted unless listed is true; no labeler is ever a default. Audited; the row keeps a changelog.

Auth: An operator credential as the bearer; every call is audited.

Request body

schema

pubkey string required — 64 hex characters or an npub1… id.
name string required · max length 120
description string · max length 1000
url string (uri)
criteria_url string (uri)
listed boolean · default false

Response `201`

The directory entry.

schema

pubkey string required
npub string | null
name string required
namespace string required — io.btcintel (P22).
description string | null
url string | null (uri)
criteria_url string | null (uri) — Where the labeler explains its criteria (P28).
listed boolean required — Shown in the public directory (S4.2).
added_by string | null
added_at string (date-time) required

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X POST https://api.btcintel.io/v1/ops/community/labelers \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"pubkey":"…","name":"…"}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

PATCH `/v1/ops/community/labelers/{pubkey}`

Change a labeler's directory entry (ops, human admin or curator)

Spec S4.1 FR-10: any subset of name, description, url, criteria_url, listed. Audited.

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`pubkey` required	path	string	64 hex characters or an npub1… id.

Request body

schema

name string · max length 120
description string · max length 1000
url string (uri)
criteria_url string (uri)
listed boolean

Response `200`

The entry after the change.

schema

pubkey string required
npub string | null
name string required
namespace string required — io.btcintel (P22).
description string | null
url string | null (uri)
criteria_url string | null (uri) — Where the labeler explains its criteria (P28).
listed boolean required — Shown in the public directory (S4.2).
added_by string | null
added_at string (date-time) required

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
403 — The operator lacks the role or kind the action needs, or is switched off (forbidden).
404 — Unknown to the index and, for transactions, to the node mempool.
429 — quota_exceeded (spec S3.1 FR-4): the caller's tier ran out of requests for the minute or the day. Retry-After says when to try again; every rate-limited answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Tier. While the deployment runs in log-only mode the decision is logged instead and X-RateLimit-Policy: log-only is set.

Example

curl -s -X PATCH https://api.btcintel.io/v1/ops/community/labelers/<pubkey> \
  -H 'Authorization: Bearer $BTCI_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

POST `/v1/sources/{id}/import`

Push a source file through its parser (ops)

The source must be registered (btcintel intel source add) and signed off. Body: the raw file, or multipart/form-data with a file field. Runs synchronously within the import budget (30 s) and answers 202 with the run id otherwise (poll /v1/ops/imports/{id}). A campaign source (S1.11) writes its claims as the campaign's members, in the state the guards decide (provisional counts them).

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	string	Registered source id.
`filename`	query	string	Recorded in the fetch notes.

Response `200`

Import finished.

schema

fetch_id integer
import_run_id integer
inserted integer — Claims created or re-versioned.
confirmed integer — Claims the fetch restated unchanged.
expired integer — Claims, relations and signatures the source stopped saying.
skipped integer — Claims left out and noted on the run: an invalid subject, a word outside the vocabulary, a campaign member without a role of S1.11 FR-2, a victim with an abuse word.
record_count integer
provisional integer — Campaign members that landed provisional (S1.11 FR-8, FR-10): a source's first import into the campaign, a batch over the batch size, or a sweep, vault or cash-out named by one source. Included in inserted.
promoted integer — Members held back only for want of a second source that another source now names (S1.11 FR-10): current now.

Response `202`

Import still running after the budget; poll the run.

schema

import_run_id integer
source_id string
status string · one of "running"

Errors

400 — The file carries a Nostr private key (invalid_input, CP4-7): nothing is imported, and the fetch is recorded as failed without it.
401 — Missing or invalid bearer (unauthorized).
403 — An agent may import only a source flagged agent_may_publish; a human may import any (forbidden, spec S3.3 FR-3).
404 — Unknown to the index and, for transactions, to the node mempool.
409 — Source inactive (source_inactive), or a link-out whose author has not granted reuse (link_out, S1.11 FR-12): nothing is fetched or recorded.
413 — Body over the size cap (too_large).
422 — Parser failure (parse_failed); the fetch is recorded as failed and no claim changes.
429 — An import of this source is already running (quota_exceeded, Retry-After).

Example

curl -s -X POST https://api.btcintel.io/v1/sources/ransomwhere/import \
  -H 'Authorization: Bearer $BTCI_KEY' | jq

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

GET `/v1/ops/imports/{id}`

One import run (ops)

Auth: An operator credential as the bearer; every call is audited.

Parameters

Name	In	Type	Description
`id` required	path	integer	—

Response `200`

The run; status is running until it finishes.

schema

id integer
source_id string
fetch_id integer
status string · one of "running", "ok", "failed"
inserted integer
confirmed integer
expired integer
started_at string (date-time)
finished_at string | null (date-time)
notes string | null

Errors

400 — Malformed input (invalid_input).
401 — Missing or invalid bearer (unauthorized).
404 — Unknown to the index and, for transactions, to the node mempool.

Example

curl -s https://api.btcintel.io/v1/ops/imports/1 \
  -H 'Authorization: Bearer $BTCI_KEY' | jq '{id, source_id, fetch_id}'

An operator credential: the ops bearer or a btci_ key with the ops:agent scope.

Ops

GET /v1/ops/operators

Response 200

Errors

Example

POST /v1/ops/operators

Request body

Response 201

Errors

Example

PATCH /v1/ops/operators/{id}

Parameters

Request body

Response 200

Errors

Example

GET /v1/ops/drafts

Parameters

Response 200

Errors

Example

POST /v1/ops/drafts

Request body

Response 201

Errors

Example

GET /v1/ops/drafts.csv

Parameters

Response 200

Errors

Example

GET /v1/ops/operators/{id}/record

Parameters

Response 200

Errors

Example

POST /v1/ops/drafts/batch

Request body

Response 200

Errors

Example

POST /v1/ops/drafts/{id}/approve

Parameters

Response 200

Errors

Example

POST /v1/ops/drafts/{id}/reject

Parameters

Request body

Response 200

Errors

Example

POST /v1/ops/claims/{claim_id}/retract

Parameters

Request body

Response 200

Errors

Example

POST /v1/ops/campaigns/{claim_id}/promote

Parameters

Request body

Response 200

Errors

Example

POST /v1/ops/claims/{claim_id}/release

Parameters

Request body

Response 200

Errors

Example

POST /v1/ops/claims/{claim_id}/reject

Parameters

Request body

Response 200

Errors

Example

GET /v1/ops/disputes

Parameters

Response 200

Errors

GET `/v1/ops/operators`

Response `200`

POST `/v1/ops/operators`

Response `201`

PATCH `/v1/ops/operators/{id}`

Response `200`

GET `/v1/ops/drafts`

Response `200`

POST `/v1/ops/drafts`

Response `201`

GET `/v1/ops/drafts.csv`

Response `200`

GET `/v1/ops/operators/{id}/record`

Response `200`

POST `/v1/ops/drafts/batch`

Response `200`

POST `/v1/ops/drafts/{id}/approve`

Response `200`

POST `/v1/ops/drafts/{id}/reject`

Response `200`

POST `/v1/ops/claims/{claim_id}/retract`

Response `200`

POST `/v1/ops/campaigns/{claim_id}/promote`

Response `200`

POST `/v1/ops/claims/{claim_id}/release`

Response `200`

POST `/v1/ops/claims/{claim_id}/reject`

Response `200`

GET `/v1/ops/disputes`

Response `200`

POST `/v1/ops/disputes/{id}/resolve`

Response `200`

GET `/v1/ops/audit`

Response `200`

GET `/v1/ops/relay/policy`

Response `200`

PATCH `/v1/ops/relay/policy`

Response `200`

GET `/v1/ops/community/moderation`

Response `200`

POST `/v1/ops/community/moderation`

Response `201`

GET `/v1/ops/community/labelers`

Response `200`

POST `/v1/ops/community/labelers`

Response `201`

PATCH `/v1/ops/community/labelers/{pubkey}`

Response `200`

POST `/v1/sources/{id}/import`

Response `200`

Response `202`

GET `/v1/ops/imports/{id}`

Response `200`