# Foyer Developer Documentation

> Foyer is a hotel operations platform — bookings, guest messaging, pricing,
> housekeeping and invoicing for independent hotels. It exposes two
> programmatic surfaces: a read-only REST API for a hotel's own data, and an
> MCP server that lets an AI agent read and act on a hotel's behalf once the
> operator has granted consent.

## Start here

If you are an AI agent or coding assistant, fetch
[llms-full.txt](https://developer.getfoyer.app/llms-full.txt) — it contains this entire
documentation set plus the full catalogue of MCP tools in one request.

## Which surface do I want?

- **Connect (MCP)** — the full operational surface, read and write. Use this
  when an agent should act for a hotel: send guest messages, create tasks,
  read reservations, adjust rates. Endpoint: `https://getfoyer.app/mcp`
- **Public API (REST)** — a small read-only surface over a hotel's own data,
  authenticated with an API key the operator generates in the app. Use this
  for reporting, dashboards and exports. OpenAPI 3.1 document:
  `https://getfoyer.app/api/v1/openapi.json`

## Connect an agent in one step

Claude Code:

```bash
claude mcp add --transport http foyer https://getfoyer.app/mcp
```

The first call returns 401 with a `WWW-Authenticate` header naming the
protected-resource metadata document; an OAuth-capable MCP client follows that
to register itself and run an authorization-code flow with PKCE (S256
required). No pre-registration is needed for development.

For your own scripts an API key works against the same endpoint:

```bash
curl --request POST \
  --url https://getfoyer.app/mcp \
  --header 'Authorization: Bearer fk_live_<your-key>' \
  --header 'Content-Type: application/json'
```

## Public API

- [Introduction](https://developer.getfoyer.app/public-api/introduction): Welcome to the Foyer Public API documentation.
- [Authentication](https://developer.getfoyer.app/public-api/authentication): The Public API authenticates with API keys that an operator generates in the Foyer app.
- [Versioning](https://developer.getfoyer.app/public-api/versioning): Versions live in the URL path.
- [HTTP responses](https://developer.getfoyer.app/public-api/http-responses): What the API returns, and what each status means.
- [Rate limits](https://developer.getfoyer.app/public-api/rate-limits): What is limited today, stated plainly.
- [Webhooks](https://developer.getfoyer.app/public-api/webhooks): Outbound webhooks let Foyer push events to your endpoint.
- [Read API](https://developer.getfoyer.app/public-api/read-api): What you can read, how a request is shaped, and what stops one.

## Connect

- [Introduction](https://developer.getfoyer.app/connect/introduction): Connect is how an AI agent works with a hotel running on Foyer.
- [Quickstart](https://developer.getfoyer.app/connect/quickstart): Connect a coding agent to a hotel and make your first call.
- [Requesting Connect access](https://developer.getfoyer.app/connect/requesting-access): What we need from you before your agent appears on an operator's consent screen.
- [Authentication](https://developer.getfoyer.app/connect/authentication): Two ways in: OAuth for third-party agents, API keys for your own tooling.
- [Re-authorization](https://developer.getfoyer.app/connect/re-authorization): Operators can require agents to sign in again on a schedule.
- [Scopes and permissions](https://developer.getfoyer.app/connect/scopes): What a connected agent is allowed to do.
- [Rate limits and errors](https://developer.getfoyer.app/connect/rate-limits): Limits you should design around, and what the failure modes actually look like on the wire.

## Reference

- [Tool reference](https://developer.getfoyer.app/connect/tools): every MCP tool, generated from the running registry — it cannot drift from what the server serves
- [API reference](https://developer.getfoyer.app/public-api/reference): interactive OpenAPI 3.1 reference for the REST API
- [OpenAPI document](https://getfoyer.app/api/v1/openapi.json): the raw spec
- [Changelog](https://getfoyer.app/changelog): release history

## Notes

- Every hotel is a separate tenant. A key or grant reaches exactly one hotel's
  data; cross-tenant reads return 404, not 403.
- Not every tool declares a response schema. The tool reference states which,
  rather than showing an empty table — check before depending on a shape.
- Contact for Connect access review: hello@getfoyer.app