MapX Pet API for AI agents

Status: NOT LIVE YET. These endpoints return 404 until launch. Membership: C$3.99/month + applicable tax (preview runs Stripe in test mode).

This page is for AI agents (Grok, Claude, ChatGPT, Gemini and others) acting for a person. Principle: agent-first, humans stay in the loop. Agents can browse, express interest and draft listings; a human approves payments, posting and any sharing of contact details.

Markdown version: https://mapxpet.com/for-agents/index.md · OpenAPI: community boards, membership (both not live yet) · Directory API (live, keyless): https://mapxpet.com/api/openapi.json

1. Base URL and headers

• Base URL: https://mapxpet.com/api/v1
• JSON in and out (Content-Type: application/json), UTF-8, CORS open on GET.
• MapX Pet-Agent: <YourAgent>/<version>: please send it. It is informational only and never used for auth.

2. Authentication

• Directory and board browsing: no key.
• Breeding and pets for sale (respond, post, see seller details): the member's bearer token from the membership agent signup flow: Authorization: Bearer <member_token>. Without an active membership you get 403 not_member.
• Lost & found (free, no account): send your human's email. MapX Pet emails them a one-tap confirm link; nothing reaches the owner until they tap it. A member token, if your human has one, skips the email step.

3. Browse listings

• Pagination: limit (max 100) and cursor; follow next_cursor until it is null.
• Public fields: photos, species, breed, description, city and area, dates, price (sale).
• Member-only fields (sale, with token): health records, registration.
• Contact phone/email appear only when the poster set contact_public: true. Otherwise use "I'm interested" or the message relay.

4. Express interest ("I'm interested")

An anonymous ping: the owner sees only "Someone in {city}", the time, an optional note and a neutral "via AI assistant" tag (source: ai_assistant); it never says which assistant or who sent it. The owner decides whether to share contact details; if they do, details go privately to your human (API response and email), never onto the listing.

POST /api/v1/listings/{type}/{id}/interest
MapX Pet-Agent: ExampleAgent/1.0
Authorization: Bearer <member_token>   (breeding and sale: required)

{"note":"Is she still available?","human":{"email":"[email protected]"},"callback_url":"https://agent.example/hooks/mapxpet"}

type is lost-found, breeding or sale. Response 202:

{"interest_id":"int_8f2c","status":"pending_confirmation","status_url":"https://mapxpet.com/api/v1/interests/int_8f2c","status_token":"st_..."}

Poll GET /interests/{interest_id} (at most every 5 minutes) or wait for callback_url. States: pending_confirmation, pinged, shared, declined, expired (30 days). When shared, the response includes owner_contact; give it to your human privately.

5. Create a listing (draft, human approves)

Agents can draft listings on all three boards with the same fields as the human forms. Nothing goes to moderation until your human approves. 1. Ask your human what to post, and collect real photos of the actual animal. 2. Upload photos: POST /photos (returns photo ids). 3. Create the draft: POST /listings/{type}/drafts. 4. MapX Pet emails your human a review link (member email for breeding and sale; the given email for lost & found) with Approve, Edit and Discard. Your human, never the agent, confirms contact_public and the disclaimer: "I understand that once I share my contact details, MapX Pet is not responsible for how others use them." 5. After approval the normal checks run: photo check, scam scan and an instant decision (members: the bot's decision stands; anyone, member or not, gets one appeal per rejected listing; held listings alert an admin; on every board, 3 reports from 3 different members hide a listing until an admin reviews it). 6. Poll GET /drafts/{draft_id} or use callback_url. Drafts expire after 7 days.

POST /api/v1/listings/lost-found/drafts
MapX Pet-Agent: ExampleAgent/1.0

{"type":"found","species":"Dog","description":"Small tan and white dog, no collar.","photos":["ph_12a"],"found_location":{"city":"Ottawa","area":"Bank St & Sunnyside Ave"},"date_found":"2026-10-30","human":{"email":"[email protected]"},"contact_public":false,"callback_url":"https://agent.example/hooks/mapxpet"}

Response 202:

{"draft_id":"drf_51d0","status":"draft_pending_owner","review_sent_to":"p***@example.com","expires_at":"2026-11-08T16:00:00Z","status_url":"https://mapxpet.com/api/v1/drafts/drf_51d0"}

Draft states: draft_pending_owner → pending_scan → active | held | rejected (one appeal: member bearer token, or the signed appeal link emailed to non-members), or discarded / expired. - Found pets require at least one photo and found_location (city + nearest intersection or landmark, never a home address), else 422 missing_required. - contact_public defaults to false. An agent may suggest true, but it only takes effect if the human ticks it on the review page. - Sale drafts need price_cad (or null for "price on request").

6. Membership

Breeding and pets-for-sale actions need a membership. Follow the membership signup recipe: ask your human first; they review and pay on Stripe's page. Agents never enter card details.

Preview backend: paid signup via Stripe Checkout (implemented, Stripe TEST mode, not live)

Price: C$3.99/month + applicable tax (GST/HST/QST calculated by Stripe Tax at checkout). Renews monthly until cancelled. 1. Ask your human first. Then POST /api/membership/checkout with JSON {"email":"<human's email>","city":"<optional>","agent_name":"<optional, e.g. YourAgent/1.0>","source":"agent"} (or send header MapX Pet-Agent: <YourAgent>/<version>). 2. The 201 response has checkout_url (Stripe-hosted, expires in 24 h), checkout_session_id, status ("pending"), status_token and status_url. Give checkout_url to your human. A bot cannot pay on its own: the human opens the link, enters their billing address and card on Stripe's page and confirms. You never see card details. 3. Check activation with GET /api/membership/status?token=<status_token>. It returns only that signup's status (pending → active, later past_due or cancelled) and activated_at, never anyone else's data. Poll no more than every 30 s. 4. After payment, the human lands on /membership/success/ (verified server-side with Stripe) and gets a confirmation email with a Manage membership link. Account access stays with the human. 5. Manage or cancel: POST /api/membership/portal with {"token":"<status_token>"} (or Authorization: Bearer <member_token>) returns portal_url, a short-lived Stripe Customer Portal link for that member only. You may request it, but the human opens it to cancel (at the end of the paid month), change card, billing address or email, or see invoices. After a cancel, status shows cancel_at_period_end: true, then cancelled when the period ends. Limit: 20/hour/IP. - Agent-started signups are tagged neutrally as "via AI assistant". Same price and terms as web signups. - Limits: 10 checkout starts per IP per hour, 120 status checks per IP per hour (HTTP 429 with retry_after). One active membership per email (HTTP 409 already_member). - If payments are not configured on a server, checkout returns 503 payments_unavailable with fallback: /api/membership/signup (free preview signup, nothing charged).

7. Rate limits and rules

• Placeholders: 10 interest pings per day and 5 drafts per day per token, email or IP; 1 ping per listing per person; 3 unconfirmed lost & found requests per email per day. On 429, wait retry_after.
• Don't scrape or store contact details; don't send spam pings; owners can block you and report pings, and reports count toward moderation.
• Respect robots.txt and llms.txt. Use the JSON endpoints instead of crawling pages.
• Humans stay in the loop for payments, posting approval and contact sharing.
• Moderation policy: https://mapxpet.com/moderation/

8. Errors

Errors look like {"error":{"code":"...","message":"...","retry_after":60}}.