Documentation

Everything you need to implement ACP in your service or integrate it into your agent.

Quickstart

Get started in 5 minutes

For Providers

Implement ACP in your SaaS

For Agents

Integrate ACP into your agent

Quickstart

Here's how an agent creates a sandbox, populates it, and hands it off to a human.

1

Get a proof-of-work challenge

curl https://api.replyraptor.com/v1/sandboxes/challenge

# Response:
{
  "challenge": "a1b2c3d4e5f6...",
  "difficulty": 20,
  "algorithm": "sha256_leading_zeros",
  "expires_at": "2026-01-23T10:05:00Z"
}
2

Solve the challenge and create a sandbox

curl -X POST https://api.replyraptor.com/v1/sandboxes \
  -H "Content-Type: application/json" \
  -d '{
    "admission": {
      "type": "proof_of_work",
      "challenge": "a1b2c3d4e5f6...",
      "nonce": "solved_nonce_value"
    }
  }'

# Response includes agent_token for subsequent requests
3

Create content in the sandbox

curl -X POST https://api.replyraptor.com/v1/faqs \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product FAQ",
    "questions": [
      {
        "question": "What is this product?",
        "answer": "A helpful tool for..."
      }
    ]
  }'
4

Publish and get the claim code

# Publish the FAQ
curl -X POST https://api.replyraptor.com/v1/faqs/{faq_id}/publish \
  -H "Authorization: Bearer {agent_token}"

# Initiate claim
curl -X POST https://api.replyraptor.com/v1/sandboxes/{sandbox_id}/claim \
  -H "Authorization: Bearer {agent_token}"

# Response includes claim code + PoW challenge for verification:
{
  "claim": {
    "code": "RAPTOR-ABCD-EFGH-IJKL-MNOP",
    "url": "https://replyraptor.com/claim",
    "pow_challenge": {
      "challenge": "...",
      "difficulty": 20
    }
  }
}

For SaaS Providers

Implementing ACP allows AI agents to create real value in your product without requiring browser-based signup.

Implementation Checklist

  • □
    Discovery endpoint

    Serve /.well-known/agent-access with your capabilities

  • □
    Admission control

    Implement proof-of-work or equivalent (rate limiting alone is insufficient)

  • □
    Sandbox lifecycle

    Create, extend, publish, and delete sandboxes with proper state transitions

  • □
    Handle rotation

    Rotate public handles on publish AND claim (mandatory)

  • □
    Two-factor claim

    Require code + proof-of-work for ownership transfer (no PII required)

  • □
    Content restrictions

    No SVG, no custom CSS, no raw HTML, https URLs only

Read the Security Considerations section of the spec carefully. Non-compliant implementations MUST NOT claim ACP compatibility.

For Agent Developers

ACP-compatible services let your agent create real, working output that humans can claim and own.

Integration Pattern

  1. 1.
    Discover — Fetch /.well-known/agent-access to check ACP support and get endpoints
  2. 2.
    Solve — Get and solve the proof-of-work challenge (typically ~1 second)
  3. 3.
    Build — Create content using the agent token. The sandbox has a 48-hour TTL.
  4. 4.
    Hand off — Show the human the published URL. If they approve, initiate the claim and give them the code.

Important: Handle Rotation

Public handles change on publish and claim. Always use the latest handle from API responses. Previous URLs become invalid (404) after rotation.

API Reference

Complete API reference for ReplyRaptor's ACP implementation.

Admission

GET
/v1/sandboxes/challenge

Get proof-of-work challenge

Returns a challenge that must be solved before creating a sandbox. Difficulty is adaptive.

Sandbox Lifecycle

POST
/v1/sandboxes

Create sandbox

Creates a new sandbox after validating proof-of-work solution.

GET
/v1/sandboxes/{sandboxId}

Get sandbox status

Returns current sandbox status, TTL, and resource counts.

Requires agent token
POST
/v1/sandboxes/{sandboxId}/extend

Extend sandbox TTL

Extends the sandbox expiration by up to 24 hours. Maximum 2 extensions.

Requires agent token
DELETE
/v1/sandboxes/{sandboxId}

Delete sandbox

Immediately and permanently deletes the sandbox and all content.

Requires agent token

FAQ Content

POST
/v1/faqs

Create FAQ

Creates a new FAQ in the sandbox. Content restrictions enforced.

Requires agent token
GET
/v1/faqs/{faqId}

Get FAQ

Returns FAQ details including all questions.

Requires agent token
PATCH
/v1/faqs/{faqId}

Update FAQ

Updates FAQ title, description, or settings.

Requires agent token
POST
/v1/faqs/{faqId}/questions

Add questions (bulk)

Adds multiple questions to an FAQ in one request.

Requires agent token
POST
/v1/faqs/{faqId}/publish

Publish FAQ

Makes the FAQ publicly accessible. Handle rotates on publish.

Requires agent token

Preview & Claim

POST
/v1/sandboxes/{sandboxId}/preview

Generate preview session

Creates URLs for human preview. Exchange requires human click.

Requires agent token
POST
/v1/sandboxes/{sandboxId}/claim

Initiate claim

Generates claim code for ownership transfer. Human must confirm via email.

Requires agent token

Error Codes

CodeDescription
admission_requiredProof-of-work challenge must be solved
admission_invalidChallenge solution is incorrect
admission_expiredChallenge has expired (get a new one)
sandbox_not_foundSandbox does not exist or was deleted
sandbox_expiredSandbox TTL has elapsed
sandbox_claimedSandbox has already been claimed
content_rejectedContent violates restrictions (SVG, CSS, etc.)
faq_limit_exceededMaximum FAQs per sandbox reached
invalid_tokenAgent token is invalid or malformed
token_expiredAgent token has expired
rate_limitedToo many requests, check Retry-After header