ABT Agent Protocol docs

Start with a sandbox Developer App for identity checks and read workflows, then request production or trusted-user access before running writes. CLI, SDK, MCP, and direct HTTPS calls share the same grant model.

1. 1Open Developer Center and create a sandbox app for the acting context: candidate, company, or internal.
2. 2For candidate search, use the Candidate job agent preset or include candidate.profile:read and candidate.jobs:read; add candidate.applications:write only for approved production apply flows.
3. 3For company conversation reads, use the Employer sourcing preset or include company.profile:read and company.messages:read; add company.messages:write, company.contact_exchange:write, and company.billing:read only for approved production workflows.
4. 4Issue a token, store it as a secret, and verify identity with GET /me before running any workflow.
5. 5For approved writes, include Idempotency-Key and explicit user confirmation.

The web route /api/agent/v1/openapi.json serves the schema. Runtime API calls use ABT_BASE_URL, which may be production or a separately running sandbox API.

export ABT_BASE_URL="https://api.aibuildertalent.com/api/agent/v1"
export ABT_API_TOKEN="abt_pat_..."

curl "$ABT_BASE_URL/me" \
  -H "Authorization: Bearer $ABT_API_TOKEN"

# CLI is available in authorized preview environments.
abt auth login --token "$ABT_API_TOKEN" --base-url "$ABT_BASE_URL"
abt me --json

Candidate read, then approved write

abt candidate jobs search --query "AI engineer" --json

# Production/trusted-user write: replace with a numeric jobs[].id after confirmation.
export JOB_ID_FROM_SEARCH="123"

abt candidate applications apply \
  --job-id "$JOB_ID_FROM_SEARCH" \
  --idempotency-key apply-demo-001 \
  --confirm \
  --json

Company read, then approved write

abt company conversations list --status open --json

# Production/trusted-user write: replace with a conversations[].id after confirmation.
export CONVERSATION_ID_FROM_LIST="456"

abt conversations messages send \
  --conversation-id "$CONVERSATION_ID_FROM_LIST" \
  --content "Hi, your AI product work looks relevant." \
  --idempotency-key msg-demo-001 \
  --confirm \
  --json

HTTPS equivalent

curl "$ABT_BASE_URL/me" \
  -H "Authorization: Bearer $ABT_API_TOKEN"

curl -G "$ABT_BASE_URL/candidate/jobs" \
  -H "Authorization: Bearer $ABT_API_TOKEN" \
  --data-urlencode "query=AI engineer" \
  --data-urlencode "page_size=10"

# Production/trusted-user write: replace with a numeric data.jobs[].id after confirmation.
export JOB_ID_FROM_SEARCH="123"

curl "$ABT_BASE_URL/candidate/applications/apply" \
  -X POST \
  -H "Authorization: Bearer $ABT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: apply-demo-001" \
  --data "{\"job_id\":$JOB_ID_FROM_SEARCH,\"contact_preference\":\"platform\",\"source_from\":\"docs_quickstart\",\"source_src\":\"abt\"}"

External automation writes never use raw web sessions. Requests authenticate a Developer App token with finite expiry, scope snapshot, acting context, app status, and billing or entitlement checks.

Suspended apps can still be inspected and cleaned up, but they cannot issue or rotate tokens until restored. Active tokens fail Agent API authentication while suspension is in effect.

• Token plaintext is shown once; store only the secret value in connected tools.
• Tokens keep their original scope snapshot until rotated or reissued.
• OpenAPI operations expose x-required-scopes so agents can preflight grants before calling protected endpoints.
• Revoking a token, grant, or app stops writes without changing historical audit records.

Every agent facade response should explain what happened and what to do next. Agents should not parse vague HTTP errors when a structured action or missing requirement is available.

{
  "ok": true,
  "data": {},
  "actions": [],
  "next_steps": [],
  "warnings": [],
  "meta": {
    "request_id": "req_...",
    "rate_limit": {},
    "credits": {}
  }
}

{
  "ok": false,
  "error": {
    "code": "MISSING_CREDIT",
    "message": "Contact exchange credit is required.",
    "missing_requirements": [
      {
        "type": "billing",
        "code": "credit_required",
        "message": "Add contact_exchange credit before retrying.",
        "action": "create_checkout"
      }
    ],
    "actions": [
      {
        "action": "get_billing_balance",
        "method": "GET",
        "endpoint": "/api/agent/v1/billing/balance"
      },
      {
        "action": "list_billing_entitlements",
        "method": "GET",
        "endpoint": "/api/agent/v1/billing/entitlements"
      },
      {
        "action": "create_checkout",
        "requires_user_confirmation": true
      }
    ],
    "retryable": false
  },
  "meta": {
    "request_id": "req_...",
    "credits": {
      "credit_type_code": "contact_exchange",
      "required": 1,
      "available": 0
    }
  }
}

• Branch on error.code, not prose.
• Use error.actions for the next safe API call.
• Retry only when retryable is true or the missing requirement has been resolved.

Company talent search is not listed here because the served v1 OpenAPI contract exposes company conversation workflows, not a company talent search endpoint.

Tool-sent messages may negotiate salary or scheduling, but direct contact details are rejected unless exchanged through the native consented contact exchange flow. Company-initiated contact exchange checks and consumes contact_exchange credit when the request is created; acceptance is still required before details are shared.

{
  "ok": false,
  "error": {
    "code": "CONTACT_DETAIL_BLOCKED",
    "message": "Message contains off-platform contact details.",
    "missing_requirements": [
      {
        "type": "contact_policy",
        "code": "native_contact_exchange_required",
        "message": "Use the native contact exchange flow before sharing contact details.",
        "action": "request_contact_exchange"
      }
    ],
    "actions": [
      {
        "action": "request_contact_exchange",
        "method": "POST",
        "endpoint": "/api/agent/v1/conversations/{conversation_id}/contact-exchange",
        "required_scopes": ["company.contact_exchange:write"],
        "requires_user_confirmation": true
      }
    ],
    "retryable": false
  },
  "meta": {
    "request_id": "req_..."
  }
}

• Blocked details include email, phone, chat handles, meeting links, payment links, and external forms.
• POST contact-exchange and respond endpoints require Idempotency-Key.
• Use the returned action hint instead of rewriting the rejected message with obfuscated contact details.

Sandbox reads and fixture-safe testing are intended to be free within limits. Production writes, high-volume automation, and native contact exchange may require credits, an active entitlement, approved company status, and healthy abuse signals.

Quota and credit values are launch-review defaults until finance, product, support, legal, and privacy review are complete.

Webhook payloads are thin events with stable event ids, resource pointers, summaries, and action hints. Receivers must dedupe by event id and fetch full objects through scoped API calls.

ABT-Timestamp: 2026-05-07T10:00:00Z
ABT-Event-ID: evt_...
ABT-Signature: v1=<hex-hmac-sha256>

signed_payload = timestamp + "." + raw_body

• Verify HMAC over ABT-Timestamp + "." + raw body.
• During secret rotation, accept any valid v1 signature in the header.
• Implemented events include application.created, application.status_changed, conversation.message.created, contact_exchange.requested, contact_exchange.accepted, contact_exchange.declined, and webhook.test.
• Production endpoints must use HTTPS and pass private-network protection.
• Use event_types ["*"] for all implemented events; prefix wildcards are not accepted.
• Suspended apps can list endpoints and rotate secrets for cleanup, but cannot create active endpoints, resume delivery, test, or replay events.

Developer App owners are responsible for their tokens, authorized automation, billing-aware writes, and compliance with native contact exchange. Public launch still requires final legal approval of terms, contact policy, paid usage, retained audit fields, and enforcement language.

• Do not scrape, resell, bulk export, or enrich ABT data outside authorized workflows.
• Do not bypass consent, contact exchange, billing, rate limits, or app status.
• Rotate or revoke tokens immediately after suspected compromise.
• ABT may suspend apps, tokens, webhook endpoints, or endpoint families for security, abuse, billing, or legal reasons.

Developer Center should collect durable access requests for production activation, higher limits, billing issues, token compromise, contact-policy blocks, webhook delivery problems, and suspension appeals. Support should use request ids and audit metadata without asking for plaintext tokens.

• Route production access and quota appeals to product/support.
• Route contact-policy blocks and suspensions to trust/support.
• Route billing credits and failed charges to finance/support.
• Route webhook signature or delivery failures to engineering/support.

Use OpenAPI for exact schema and generated clients. The checked-in YAML mirrors the served API contract.