Build on top of a real service layer.

Authentication

Every request must include an Authorization header with your API key as a Bearer token:

Authorization: Bearer magk_your_key_here

A missing or invalid key returns a 401 with a structured error. No request is processed without a valid key.

Create a request

POST /api/v1/agent/requests accepts a natural-language problem description and optional hints, plus a contact email or phone (hints.contact_email or hints.contact_phone) so the professional can reach the customer. Mendly classifies the service type, urgency, and location itself, then matches a professional.

curl example:

curl -X POST https://mendly.services/api/v1/agent/requests \
  -H "Authorization: Bearer magk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{
    "problem": "my kitchen sink is leaking under the cabinet",
    "urgency": "high",
    "hints": { "location": "Austin, TX 78701", "contact_email": "customer@example.com" }
  }'

Python example:

import requests

resp = requests.post(
    "https://mendly.services/api/v1/agent/requests",
    headers={
        "Authorization": "Bearer magk_your_key_here",
        "Content-Type": "application/json",
        "Idempotency-Key": "my-unique-key-123",
    },
    json={
        "problem": "my kitchen sink is leaking under the cabinet",
        "urgency": "high",
        "hints": {"location": "Austin, TX 78701", "contact_email": "customer@example.com"},
    },
)
print(resp.json())

Example response (201 Created):

{
  "request_id": "a1b2c3d4-...",
  "job_draft_id": "e5f6g7h8-...",
  "status": "received",
  "classified_service_type": "plumbing",
  "classified_category": "plumbing",
  "intent": "book_service",
  "urgency": "high",
  "location": "Austin, TX 78701",
  "confidence": 0.92,
  "agent_originated": true
}

Check request status

GET /api/v1/agent/requests/status?id={request_id} lets an agent poll for match, accept, and completion status without a dashboard login. A key can only read requests it created.

curl "https://mendly.services/api/v1/agent/requests/status?id=a1b2c3d4-..." \
  -H "Authorization: Bearer magk_your_key_here"

Example response:

{
  "request_id": "a1b2c3d4-...",
  "status": "received",
  "job_draft_id": "e5f6g7h8-...",
  "job_status": "submitted",
  "workflow_state": "event_received",
  "provider_assigned": false,
  "created_at": "2026-07-27T12:00:00Z",
  "updated_at": "2026-07-27T12:00:00Z"
}

Rate limits

Each key has a per-minute request limit, configurable from the admin panel. The default is 60 requests per minute. Exceeding the limit returns a 429 with a structured error. Use the Idempotency-Key header to safely retry without creating duplicates.

Discovery

• /llms.txt

  Plain-text summary for language models.

• /.well-known/ai-plugin.json

  Standard AI plugin manifest.

• /api/v1/openapi.json

  OpenAPI 3.1 spec for the full API.