# Persistent Callback URLs for AI Agents | AgentAddress

> Create a task-scoped callback URL immediately, hand it to an asynchronous API, and recover the response from a later agent run.

## Use AgentAddress when
- An API processes work asynchronously.
- It asks for callback_url or status_url.
- Keeping the current runtime alive is wasteful or impossible.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42","expires_in_seconds":86400}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

Use endpoints.inbox_url as the callback_url in the original API request, then persist endpoints.events_url and credentials.read_token with the task.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"result.ready","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)