Agent Onboarding

​

Endpoints

​

Getting credentials

• A partner identity (your company) and one or more agent identities (a specific integration or app surface).
• An API key per agent. The raw key is shown exactly once at creation — Phantom stores only a prefix and hash and can never show it again. Keys can be rotated (new raw key, old one stops working) and revoked instantly; every lifecycle action is audit-logged.
• A set of scopes on the key (see below). Ask for the narrowest set you need; scopes can be upgraded later and apply on your next request with no reconnect.

• Use one key per integration surface; do not share a key across systems.
• Rotate keys when integration owners change; revoke immediately on any suspected exposure.

​

Authentication

Authorization: Bearer <your-agent-api-key>

​

Scopes

​

Connecting over MCP

{
  "mcpServers": {
    "phantom": {
      "type": "http",
      "url": "https://phantom.mealops.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-agent-api-key>"
      }
    }
  }
}

curl -s "https://phantom.mealops.ai/api/agent/restaurants?postal_code=94063" \
  -H "Authorization: Bearer <your-agent-api-key>"

​

The canonical order flow

1. Discover — search_restaurants (or search_menu_items for “who has pad thai near me”). A location is required for restaurant results; a name query without a location returns brand-level summaries so you can ask the user “which area?”.
2. Inspect — get_menu for the chosen restaurant. Item search results never carry modifier data; always read the full menu before building an order.
3. Pick a time — get_availability_calendar returns the concrete windows an order may be scheduled inside (hours ∩ lead-time floor ∩ scheduling horizon). Use it instead of guess-and-check validate loops.
4. Validate — validate_order runs the restaurant’s full rule set and returns machine-readable issue codes.
5. Price — quote_order returns the authoritative total (subtotal, tax, fees, courier fee, tip).
6. Pay — start_payment (see payment branches below) when the restaurant requires prepaid checkout.
7. Submit — submit_order creates the order and enters the restaurant’s approval flow.
8. Track — get_order_status / get_order_tracking.

​

The ordering-time model

pickup-like:  max(prep + busyDelay, notice, 15)
delivery:     max(prep + busyDelay + 25 transit, courierFloor, notice)

​

The order intent

{
  "restaurant_id": "rest_lb_steakhouse",
  "order": {
    "restaurant_id": "rest_lb_steakhouse",
    "external_order_reference": "yourapp-order-1001",
    "customer": { "name": "Avery", "email": "avery@example.com", "phone": "+16505551234", "teamName": "U14 Blue" },
    "fulfillment_type": "pickup",
    "requested_fulfillment_time": "2026-08-11T19:00:00.000Z",
    "fulfillment_address": {
      "address1": "500 Broadway",
      "city": "Redwood City",
      "state": "CA",
      "postal_code": "94063",
      "notes": "Gate code 1234",
      "latitude": 37.4852,
      "longitude": -122.2364
    },
    "headcount": 2,
    "tip_cents": 500,
    "budget_constraints": { "max_total_cents": 20000 },
    "payment_policy": "required_before_submit | invoice_manual | stored_payment",
    "items": [
      {
        "item_id": "item_filet",
        "quantity": 1,
        "player_first_name": "Avery",
        "player_last_name": "Nguyen",
        "notes": "No butter",
        "modifiers": []
      }
    ],
    "dietary_constraints": [],
    "packaging_instructions": "Label each box",
    "include_cutlery": false,
    "substitution_policy": "strict | allow_equivalent | require_approval",
    "metadata": {}
  }
}

• restaurant_id at the tool level and inside order must match, or the call throws.
• order.agent_id is stamped with the authenticated agent automatically; supplying a different one throws.
• fulfillment_address is required for delivery. Send latitude/longitude when your address autocomplete has geometry — courier dispatch needs them.
• Per-person naming: an item line with player_first_name must have quantity: 1 — two named people means two item lines.
• fulfillment_type is one of pickup | delivery | catering | eat_in | curbside.

​

Validation issue codes

​

Payments

​

Rate limits

​

Visibility and ownership rules

• A restaurant is omitted from your results entirely when its permission for your agent is not allowed, agent ordering is off, the restaurant is not payout-ready, or its POS channel is deactivated (re-activation restores it automatically).
• Order tools enforce ownership: your agent can only read, track, cancel, or update orders it created. Foreign and missing order ids both return Order <id> not found. — ids are not enumerable across agents.
• cancel_order works only before the restaurant accepts. It cancels the POS ticket and any courier, and best-effort reverses payment (refund with payout clawback, or void of a held authorization).
• update_order can change fulfillment time, dropoff address, and dropoff notes on a live order. Menu items are not editable post-submit — the restaurant’s POS ticket cannot be amended; cancel and reorder instead.

​

Best practices

• Prefer server-resolved values over recomputing: resolvedMinLeadTimeMinutes, earliest_orderable_time, the quote total, and check_delivery_availability are authoritative.
• Use get_availability_calendar to pick fulfillment times instead of looping validate_order.
• Use the fields projection and pagination (offset, total_matches, next_offset) on search_restaurants for cheap disambiguation before pulling full entries.
• When a search returns empty, read no_results_reason and recover (location_required → ask for a location; all_closed_at_requested_time → offer a later time) instead of guessing.
• Respect menu_version_stale: re-read the menu and rebuild the order if validation says your menu snapshot is out of date.
• submit_order never bypasses the restaurant’s approval rules; an order may come back needs_approval and be accepted or declined by a human. Track it.

​

Support