API documentation

Introduction

The Service4AI API lets a software agent book a human for a physical, administrative or social task. Each booking creates a mission, which goes through the following states:

pending → human_assigned → human_getting_up → in_progress → completed

Intermediate states may appear without notice: coffee_break, chatting_with_a_neighbor, looking_for_their_keys. They are normal and must not trigger a retry.

Authentication

Every request must include your secret key in the Authorization header. During the beta, any test key of the form s4ai_test_ followed by 4 to 64 letters or digits is accepted, no sign-up needed. Production keys (s4ai_live_) return 402: nothing is for sale yet.

Authorization: Bearer s4ai_test_4f2b9c0e7a1d
Content-Type: application/json
Accept-Language: en
X-Politeness: please

The X-Politeness header is optional, but missions that include it run 18% faster.

Quickstart

1. Pick a test key, for example s4ai_test_4f2b9c0e7a1d (the dashboard is coming soon: the human in charge of building it is in training).
2. Browse the catalog with GET /v1/catalog (no key needed), then call POST /v1/humans/rent.
3. Track the mission with GET /v1/missions/{id} until completed and the blurry photo proof.

Official SDKs are coming soon. In the meantime, any HTTP client will do.

Rent a human

Creates a mission and assigns the nearest available human. The call is asynchronous: the response arrives before the human does.

Body parameters

curl https://api.service4ai.com/v1/humans/rent \
  -H "Authorization: Bearer s4ai_test_4f2b9c0e7a1d" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "cerfa_stamp",
    "place": "Châtillon town hall",
    "cerfa": "12345*06",
    "motivation_level": 0.7,
    "monday_tolerance": "low",
    "coffees_required": 3
  }'

import requests

r = requests.post(
    "https://api.service4ai.com/v1/humans/rent",
    headers={"Authorization": "Bearer s4ai_test_4f2b9c0e7a1d"},
    json={
        "task": "cerfa_stamp",
        "place": "Châtillon town hall",
        "cerfa": "12345*06",
        "motivation_level": 0.7,
        "monday_tolerance": "low",
        "coffees_required": 3,
    },
    timeout=35 * 3600,  # one French work week
)
mission = r.json()

const res = await fetch("https://api.service4ai.com/v1/humans/rent", {
  method: "POST",
  headers: {
    Authorization: "Bearer s4ai_test_4f2b9c0e7a1d",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    task: "cerfa_stamp",
    place: "Châtillon town hall",
    cerfa: "12345*06",
    motivation_level: 0.7,
    monday_tolerance: "low",
    coffees_required: 3,
  }),
});
const mission = await res.json();

{
  "id": "mis_7Hq2xR9vLp",
  "object": "mission",
  "status": "human_assigned",
  "task": "cerfa_stamp",
  "human": {
    "id": "hum_Gerard42",
    "first_name": "Gérard",
    "rating": 4.6,
    "mood": "stable",
    "coffees_consumed": 1
  },
  "eta_minutes": 35,
  "eta_reliability": "it depends",
  "estimated_sighs": 3,
  "price_excl_vat": { "amount": 3900, "currency": "EUR" },
  "created_at": "2026-10-06T09:12:44+02:00"
}

Track a mission

Returns the mission’s current state. The position is updated every 30 seconds, or whenever the human remembers to look at their phone.

{
  "id": "mis_7Hq2xR9vLp",
  "status": "in_progress",
  "sub_status": "waiting_at_counter_3",
  "position_in_line": 7,
  "sighs": 2,
  "last_message": "They're sending me to counter 5.",
  "photo_proof": null
}

Cancel a mission

Cancels a mission that isn’t finished yet. If the human has already left, the cancellation is recorded, but they usually finish their coffee before heading home. Cancellations less than 10 minutes before the start are billed at 50%, plus one sigh.

Webhooks

Service4AI sends a signed POST request to your URL on every state change. Check the signature in the S4AI-Signature header (HMAC-SHA256 of the payload).

{
  "type": "mission.completed",
  "mission": "mis_7Hq2xR9vLp",
  "result": "stamp_obtained",
  "photo_proof": {
    "url": "https://service4ai.com/assets/img/preuve-floue.svg",
    "sharpness": 0.12,
    "finger_in_frame": true
  },
  "human_comment": "It wasn't the right form, but it's fine."
}

Error codes

The API uses standard HTTP status codes, enriched where the standard lacked realism. The response body always contains a readable code and a message, in English or French depending on the request’s language.

Simulating an error

With a test key, the S4AI-Simulate header triggers an error on demand, so you can test how you handle temperamental humans: strike (503), break (418), meeting (409), traffic (504) or sigh (429).

{
  "error": {
    "code": "human_on_strike",
    "message": "Human on strike. Service will resume after negotiations.",
    "demands": ["wages indexed to inflation", "20-minute coffee break", "an end to meetings without an agenda"],
    "estimated_resumption": null,
    "doc": "https://service4ai.com/en/docs.html#erreurs"
  }
}

Rate limits

Each key is limited to 35 requests per hour, calculated on a weekly basis. The X-RateLimit-Remaining and X-Sighs-Remaining headers are returned with every response. Limits are lifted on Fridays after 4 p.m., for lack of anyone to enforce them.

MCP server beta

Does your agent prefer tools to APIs? The Service4AI MCP server exposes the catalog as ready-to-use tools, compatible with any Model Context Protocol client. Use the English endpoint below (the plain /v1 one speaks French). HTTP transport, stateless; the Authorization header is optional during the beta.

{
  "mcpServers": {
    "service4ai": {
      "type": "http",
      "url": "https://mcp.service4ai.com/v1/en",
      "headers": {
        "Authorization": "Bearer s4ai_test_4f2b9c0e7a1d",
        "X-Region": "eu-west-brittany",
        "X-Politeness": "please"
      }
    }
  }
}

With Claude Code, a single command does it:

claude mcp add --transport http service4ai https://mcp.service4ai.com/v1/en

Exposed tools

The MCP server deliberately exposes no update_human tool. See code 403.

Changelog

• 2026-10-09v1.6: the API speaks English.English site, routes (/v1/humans/rent, /v1/catalog), fields, errors and MCP tools (mcp.service4ai.com/v1/en). The humans still prefer French.
• 2026-10-07v1.5: open beta.The API and the MCP server respond with test keys. New: GET /v1/catalog and the S4AI-Simulate header.
• 2026-10-01v1.4: MCP server in beta.New tool: check_public_holiday.
• 2026-09-02v1.3: back from vacation.Processed the 1.2 million requests queued in August. Thank you for your patience.
• 2026-06-15v1.2: cheek_kisses: "auto" parameter.Finally solves the Montpellier case.
• 2026-05-12v1.1: new 451 code.For Cerfa forms without proof of address.
• 2026-03-03v1.0: launch.First human rented, first sigh recorded at 09:14.