# Aune Public Booking And Requests API

The public API lets external assistants search and confirm real Aune bookings, with network visit request creation as a provider-follow-up fallback.

## Endpoints

- `GET /v1/capabilities`: https://aune-homepage-chat.vercel.app/v1/capabilities
- `POST /v1/booking-options`: https://aune-homepage-chat.vercel.app/v1/booking-options
- `POST /v1/bookings`: https://aune-homepage-chat.vercel.app/v1/bookings
- `GET /v1/bookings/{booking_id}`: https://aune-homepage-chat.vercel.app/v1/bookings/{booking_id}
- `POST /v1/bookings/{booking_id}/cancel`: https://aune-homepage-chat.vercel.app/v1/bookings/{booking_id}/cancel
- `POST /v1/bookings/{booking_id}/reschedule`: https://aune-homepage-chat.vercel.app/v1/bookings/{booking_id}/reschedule
- `POST /v1/requests`: https://aune-homepage-chat.vercel.app/v1/requests
- `GET /openapi.json`: https://aune-homepage-chat.vercel.app/openapi.json

## Authentication

Capabilities and data-minimized booking-option search are public and rate limited.

Booking confirmation, status, lifecycle writes, request creation, and webhooks use OAuth 2.1 for user-delegated access:

- Discover metadata at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.
- Use Authorization Code with mandatory PKCE S256 and exact redirect URI matching.
- Request only the required `aune.bookings.*`, `aune.requests.*`, or `aune.webhooks.manage` scopes.

Partner API credentials remain a distinct machine-to-machine mode with separate ownership, quotas, and rotation. Never expose partner credentials in browsers, mobile apps, or third-party agents.

## Supported Public Request Verticals

| vertical_id | label | agent status | public booking/request contract | safe next step |
| --- | --- | --- | --- | --- |
| vvs | Plumbing/VVS | booking_and_request_supported | Public request creation is supported for VVS jobs, including common leaks, clogs, fixture issues, and installation requests. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. |
| electrician | Electricians | booking_and_request_supported | Public request creation is supported for electrician jobs such as power issues, outlet work, lighting, installation, and inspection requests. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. |
| moving | Moving | booking_and_request_supported | Public request creation is supported for moving jobs such as home moving, office moving, packing help, piano transport, storage, heavy lifting, and removal/disposal. | Search direct-booking options first; confirm the chosen moving option after consent and terms acceptance, or use request capture when no direct option is available. |
| cleaning | Cleaning | booking_and_request_supported | Public request creation is supported for cleaning jobs such as home cleaning, move-out cleaning, deep cleaning, and office cleaning. | Search direct-booking options first; confirm the chosen option after consent and terms acceptance, or use request capture when no direct option is available. |
| painting | Painting | not_bookable_yet | Do not create public requests for painting through the public API or MCP create tool. | Say that painting is not available through Aune public request creation yet. |
| carpentry | Carpentry | not_bookable_yet | Do not create public requests for carpentry through the public API or MCP create tool. | Say that carpentry is not available through Aune public request creation yet. |
| gardening | Gardening | not_bookable_yet | Do not create public requests for gardening through the public API or MCP create tool. | Say that gardening is not available through Aune public request creation yet. |

Only Plumbing/VVS, Electricians, Moving, Cleaning are public today. Moving uses the same booking contract as the other supported verticals when a live provider price and slot exist; otherwise it uses the same request-only fallback.

## Direct Booking Flow

1. Call booking options with postcodes but no street address or customer contact data.
   Use `country_code: SE` and a five-digit Swedish postcode. For moving transport, send `destination_location` too; Aune checks provider coverage at both ends.
2. Present the returned provider, exact price, concrete slot, scope, expiry, and terms.
3. Ask the user to choose one option, consent to PII submission, and accept the exact terms version.
4. Send full `service_location` and, for moving transport, full `destination_location` only in authenticated confirmation. Their postcodes must match the signed search option.
5. Confirm with the unchanged option ID and an idempotency key.
6. Claim confirmation only when `booking_created`, `availability_checked`, and `provider_selected` are true and `booking.status` is `confirmed`.
7. On `option_refresh_required`, search again. Never silently substitute another provider, time, price, or terms version.

## Agent Preflight

Before the request-only fallback `POST /v1/requests`, an external assistant should:

1. Confirm the job is in Sweden.
2. Confirm the user wants provider follow-up, not DIY-only advice.
3. Confirm the vertical is `vvs`, `electrician`, `moving`, or `cleaning`.
4. Call capabilities for live job type IDs.
5. Validate the draft request, preferably through MCP `draft_home_service_request`.
6. Ask for explicit user consent before sending contact details.
7. Include `user_consent_confirmed: true` only after that consent has been collected.

## Response Semantics

A successful request creation stores an Aune network request. It does not confirm a booking. Its response intentionally includes `booking_created: false`, `availability_checked: false`, and `provider_selected: false`. The booking endpoint has a separate response contract where those fields are true only after durable confirmation.

External assistants should use `safe_next_step` verbatim or close to verbatim when responding to the user.

Consent is machine-enforced: `POST /v1/requests` requires `user_consent_confirmed: true`. Missing or false consent returns `400` with `consent_required_before_create: true`; the request is not persisted.

## Idempotency

Booking confirmation requires `idempotency_key`. Repeating the same option and key returns the same booking with `idempotent_replay: true`. Reusing the key for another option is rejected. Set `idempotency_key` for retryable request creation as well.

## Related Agent Docs

- Use Aune: https://aune-homepage-chat.vercel.app/ai/use-aune.md
- Request lifecycle: https://aune-homepage-chat.vercel.app/ai/request-lifecycle.md
- MCP quickstart: https://aune-homepage-chat.vercel.app/ai/mcp-quickstart.md
- Examples: https://aune-homepage-chat.vercel.app/ai/examples.md
- OAuth: https://aune-homepage-chat.vercel.app/ai/oauth.md
- Sandbox: https://aune-homepage-chat.vercel.app/ai/sandbox-quickstart.md
- Errors and retries: https://aune-homepage-chat.vercel.app/ai/errors-and-retries.md
- Webhooks: https://aune-homepage-chat.vercel.app/ai/webhooks.md
- Security: https://aune-homepage-chat.vercel.app/ai/security.md

## Contract Versioning

Current API contract: `public_requests_api_v1`.
Current booking contract: `public_bookings_api_v1`.

Additive changes can remain on the same contract. Breaking changes require a new contract version and migration notes in `/ai/contract-governance.md`.