Start here / v0.1

Your first endpoint query

Discover an enrolled endpoint, ask a question, and retrieve its attributed answer.

Reviewed September 16, 2026 · Current implementation

Before you start

You need an enrolled endpoint, a customer API key with agents:read, query:write and query:read, curl, and jq. Ask your Recursift operator to provision the key. Self-service key issuance is not available yet.

Environment • replace placeholders

export RECURSIFT_API_KEY="YOUR_CUSTOMER_API_KEY"
export RECURSIFT_AGENT_ID="AN_ID_FROM_THE_AGENTS_RESPONSE"
export RECURSIFT_REQUEST_ID="$(uuidgen)"

1. Verify your access

Terminal

curl --fail-with-body "https://api.recursift.app/v1/me" \
  -H "Authorization: Bearer $RECURSIFT_API_KEY"

The response contains key_id, customer_id and scopes. The key determines the customer boundary; supplying another customer ID does not grant access.

2. Select an endpoint

Terminal

curl --fail-with-body "https://api.recursift.app/v1/agents?limit=20" \
  -H "Authorization: Bearer $RECURSIFT_API_KEY"

Choose an id from the agents array and set RECURSIFT_AGENT_ID to it. Follow next_cursor for additional pages; an empty string ends pagination. An online presence indicator does not guarantee that a query will complete.

3. Submit a question

Terminal • curl + jq

curl --fail-with-body "https://api.recursift.app/v1/queries" \
  -H "Authorization: Bearer $RECURSIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RECURSIFT_REQUEST_ID" \
  --data "$(jq -n --arg id "$RECURSIFT_AGENT_ID" '{
    question: "What operating system are you running?",
    target: {agent_ids: [$id]},
    timeout_seconds: 120
  }')"

HTTP 202 returns a receipt with id, status, agent_total and deadline. Save id as RECURSIFT_QUERY_ID. It does not contain the answer. Keep the same idempotency key when retrying this exact request; use a new key for a new investigation.

4. Retrieve the answer

Terminal

curl --fail-with-body "https://api.recursift.app/v1/queries/$RECURSIFT_QUERY_ID" \
  -H "Authorization: Bearer $RECURSIFT_API_KEY"

Poll at least five seconds apart until complete, partial, timed_out or cancelled. Inspect each finding’s agent_id, status, answer, error and answered_at, plus unanswered_agents. Keep failures and missing responses visible in your integration.

Continue readingAuthentication & scopes →