Documentation

Getting Started

AgentReserve provides restaurant reservation infrastructure for AI agents. Your agent calls our API to book, cancel, or modify reservations -- we handle idempotency, policy enforcement, and audit logging.

1. Create an account

Register for an account and create an organization. Each organization is a fully isolated tenant with its own API keys, policies, and transaction history.

2. Generate an API key

Navigate to the API Keys page in the dashboard. Your key is displayed once at creation -- copy and store it securely.

export AGENTRESERVE_API_KEY="ar_live_abc123..."

3. Make your first booking

Call the restaurant booking endpoint with your API key. Include an Idempotency-Key header to prevent duplicate bookings.

curl -X POST https://your-host/api/v1/agent/restaurant/book \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Idempotency-Key: booking-001" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurantName": "Golden Gate Grill",
    "city": "San Francisco",
    "partySize": 4,
    "datetime": "2026-03-20T19:00:00Z",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Authentication

All API requests must include a Bearer token in the Authorization header:

Authorization: Bearer ar_live_your_api_key_here

Keys are scoped to a single organization. They are prefixed with ar_live_ for production and ar_test_ for sandbox environments. Requests without a valid token receive a 401 Unauthorized response.

API Keys

API keys are the primary authentication mechanism for the agent API.

• Keys are hashed with SHA-256 before storage. The raw key is shown once at creation and cannot be recovered.
• The first 8 characters (the keyPrefix) are stored in plaintext for identification in the dashboard.
• Keys track a lastUsedAt timestamp, updated on every authenticated request.
• Keys can be revoked at any time from the dashboard. Revoked keys immediately stop working.
• Optional expiresAt field for automatic expiration.

Create key → show raw key once → hash + store
                                    ↓
                         Agent uses raw key
                                    ↓
                         Server hashes incoming key → compare with stored hash
                                    ↓
                         Match → authenticated | No match → 401

Booking API

{
  "restaurantName": "Golden Gate Grill",
  "city": "San Francisco",
  "partySize": 4,
  "datetime": "2026-03-20T19:00:00Z",
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
}

{
  "transactionId": "cm3abc123def",
  "status": "confirmed",
  "reservation": {
    "reservationId": "cm3xyz789ghi",
    "restaurantName": "Golden Gate Grill",
    "city": "San Francisco",
    "partySize": 4,
    "datetime": "2026-03-20T19:00:00Z"
  }
}

Cancel API

{
  "transaction_id": "cm3abc123def",
  "reason": "Customer requested cancellation"
}

{
  "transactionId": "cm3abc123def",
  "status": "cancelled",
  "reservation": {
    "reservationId": "cm3xyz789ghi",
    "restaurantName": "Golden Gate Grill",
    "city": "San Francisco",
    "cancelledAt": "2026-03-15T14:00:00Z"
  }
}

Modify API

{
  "transaction_id": "cm3abc123def",
  "updates": {
    "partySize": 6,
    "datetime": "2026-03-21T20:00:00Z",
    "customer": {
      "name": "Jane Smith"
    }
  }
}

{
  "transactionId": "cm3abc123def",
  "status": "modified",
  "reservation": {
    "reservationId": "cm3xyz789ghi",
    "restaurantName": "Golden Gate Grill",
    "city": "San Francisco",
    "partySize": 6,
    "datetime": "2026-03-21T20:00:00Z"
  }
}

Idempotency

All agent endpoints support the Idempotency-Key header. This guarantees at-most-once execution -- critical for AI agents that may retry on network failures.

How it works

• First request: the operation executes normally and the response is cached for 24 hours.
• Identical replay: the cached response is returned immediately without re-executing.
• Mismatched payload: if you reuse a key with different request body, you receive 409 Conflict.

# First request — executes the booking
curl -X POST .../api/v1/agent/restaurant/book \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Idempotency-Key: booking-xyz-001" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Retry with same key + same body — returns cached response
curl -X POST .../api/v1/agent/restaurant/book \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Idempotency-Key: booking-xyz-001" \
  -H "Content-Type: application/json" \
  -d '{ ... }'   # ← 201 (cached, no duplicate booking)

Idempotency records are stored in the database with a SHA-256 hash of the normalized request body. Keys are scoped per-organization to prevent cross-tenant collisions.

Policies

Policies are guard-rails that are evaluated before any transaction executes. They allow organization admins to control what agents can do.

Policy types

Policy outcomes

• allow -- the transaction proceeds normally.
• deny -- the transaction is rejected with 403 POLICY_VIOLATION.
• requires_approval -- the transaction is created with status requires_approval and needs manual review.

MCP Tools

AgentReserve exposes an MCP-compatible tool server at /api/v1/mcp. This lets you connect Claude, GPT, or any MCP-compatible agent framework directly to AgentReserve.

Configuration

{
  "mcpServers": {
    "agentreserve": {
      "url": "https://your-host/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ar_live_abc123..."
      }
    }
  }
}

Available tools

• book_reservation -- Create a new booking through the transaction engine.
• cancel_reservation -- Cancel an existing booking by transaction ID.
• modify_reservation -- Modify time slot, party size, or customer details.

MCP tool calls are thin wrappers over the same transaction engine used by the REST API. All policy checks, idempotency guarantees, and audit logging apply identically.

Example cURL Requests

Book a table

curl -X POST https://your-host/api/v1/agent/restaurant/book \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Idempotency-Key: book-golden-gate-001" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurantName": "Golden Gate Grill",
    "city": "San Francisco",
    "partySize": 4,
    "datetime": "2026-03-20T19:00:00Z",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Cancel a reservation

curl -X POST https://your-host/api/v1/agent/restaurant/cancel \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "cm3abc123def",
    "reason": "Customer changed plans"
  }'

Modify a reservation

curl -X POST https://your-host/api/v1/agent/restaurant/modify \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "cm3abc123def",
    "updates": {
      "partySize": 6,
      "datetime": "2026-03-21T20:00:00Z"
    }
  }'

MCP tool call (book via MCP)

curl -X POST https://your-host/api/v1/mcp \
  -H "Authorization: Bearer $AGENTRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "book_reservation",
      "arguments": {
        "provider": "mock",
        "service_type": "consultation",
        "customer": {
          "name": "Jane Doe",
          "email": "jane@example.com"
        },
        "time_slot": {
          "start": "2026-03-20T10:00:00Z",
          "end": "2026-03-20T11:00:00Z"
        }
      }
    }
  }'