Connect your system to the linqo calendar

Overview

The API is REST over JSON and answers at https://v1.uselinqo.com. Every key belongs to one company: everything it reads and writes stays inside that account, no exceptions.

This entire page — routes, fields, enums and error codes — is generated from GET /v1/openapi, the contract the server itself publishes, derived from the code that answers the calls. A new route or a new field shows up here without anyone rewriting anything, and it is the same document a client generator consumes.

const res = await fetch('https://v1.uselinqo.com/v1/openapi');
const spec = await res.json();

That endpoint is public: no credential, no quota, served with Cache-Control: public, max-age=300. A description that required the very key it explains would be useless to anyone still deciding whether to integrate.

API keys

The account administrator issues keys from the dashboard. At creation they pick a name, the scopes and, optionally, an expiry date.

• The token is shown exactly once. It only exists in the creation response: what we store is a hash, and there is no way to recover the original. Copy it right away and keep it in a secrets manager — if you lose it, issue another.
• At least one scope is required. A key only reaches what its scopes allow; everything else answers SCOPE_MISSING.
• Notifications start switched off. This is deliberate: a key created without much thought cannot send email to the company’s clients. Turning it on is an explicit decision by whoever administers the account.
• Rate limit and quota are not configurable. The per-minute and per-month ceilings belong to the platform, not to the account. The dashboard shows the numbers; nobody edits them.
• Revoking takes up to 60 seconds. The authorization decision is cached for a minute, so a revoked key may still answer within that window. Plan credential rotation around it.

Authentication

Every route other than /v1/openapi expects the key in the Authorization header, as a Bearer token.

Authorization: Bearer bk_prod_<keyId>.<secret>

The environment travels inside the token itself. A development key pasted into production fails while the token is being read, with a message that says so — not as an unexplained 401.

Scopes

Each route requires at most one scope, and a key carries whichever ones the administrator picked. Grant the minimum the integration needs: a read-only key that leaks cannot book anything.

3 routes require no scope:

• GET /v1/openapi — requires no credential at all.
• GET /v1/meta — accepts any valid key.
• POST /v1/mcp — accepts any valid key.

Rate limits and quotas

There are two per-minute buckets — one for reads, one for writes — and a monthly quota per key. Each route declares which bucket it falls into: that is the cost shown on its card below.

Agents do not have a bucket of their own. Through /v1/mcp, only tools/call spends, and it spends what the route behind the tool would — a read or a write; tools/list and server/discover are free. See AI agents.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset: read those headers instead of counting calls on your side. Blowing the minute returns RATE_LIMITED and blowing the month returns QUOTA_EXCEEDED, both with status 429 — the first clears on its own, the second only at the turn of the month.

Every response also carries X-Request-Id. Keep the value in your logs: it is how support finds the call.

Pagination

Listings accept limit and cursor and return data along with next_cursor. The cursor is opaque: pass the value back exactly as it came, without interpreting it.

let cursor = null;
do {
  const url = new URL('https://v1.uselinqo.com/v1/services');
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.LINQO_API_KEY}` },
  });
  const page = await res.json();

  handle(page.data);
  cursor = page.next_cursor;
} while (cursor);

Paginate until next_cursor comes back null, never until a page comes back short. The database cuts the read at 1 MB, so a page with few items can still carry a cursor — stopping there would silently leave records behind.

Idempotency

Booking an appointment requires the Idempotency-Key header. Without it the call is refused with IDEMPOTENCY_KEY_REQUIRED.

The reason is concrete: whoever hit a timeout cannot tell “my attempt went through” from “someone else took the slot”. With the key, repeating the request returns the earlier response instead of booking twice. The response is kept for 24 hours; the same key with a different body is a 400, IDEMPOTENCY_KEY_REUSED.

Generate a fresh value per booking attempt — a UUID does the job — and reuse it across every retry of that same attempt.

Field selection

Listings accept fields with comma-separated names, to return only what your screen uses. A name the resource does not publish returns INVALID_FIELDS — the error is explicit on purpose, so that a mistyped field does not become a silently empty column.

curl 'https://v1.uselinqo.com/v1/services?fields=id,name,price' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

Errors

Other than 401, every error arrives in the same envelope: { code, message }. Program against code, which is stable; message is for a human reading a log.

AI agents

An AI agent reaches the same /v1 surface through POST /v1/mcp, which speaks the Model Context Protocol — JSON-RPC over HTTP — instead of REST. A tool is only listed, and only callable, when the connection holds the scope its route requires.

Quick start

Three steps in Claude Code. The account administrator needs to be the one approving in step 2.

1. Add the server. In a terminal:
   TerminalCopy

   claude mcp add --transport http linqo https://v1.uselinqo.com/v1/mcp

2. Authenticate. Inside Claude Code, run /mcp, pick linqo and choose Authenticate. The browser opens on the linqo dashboard: sign in, review the scopes and approve.
3. Check it worked. /mcp now lists linqo as connected, with its tools. Ask the agent what it can do with linqo — it discovers the tools on its own; there is nothing to configure.

Connect with OAuth

This is what the quick start uses. An MCP client with OAuth support needs only the URL — no key is copied anywhere. In clients configured by file, such as Cursor, declare just the URL; the client opens the browser the first time it connects:

{
  "mcpServers": {
    "linqo": {
      "url": "https://v1.uselinqo.com/v1/mcp"
    }
  }
}

What happens behind the scenes:

1. The first call, without a credential, answers 401 with WWW-Authenticate pointing to the resource metadata (RFC 9728). From there the client discovers the authorization server (RFC 8414).
2. The client opens the browser on the linqo dashboard. The account administrator signs in, sees which app is asking and where the answer goes, and approves — any requested scope can be unchecked first.
3. The client exchanges the code for an access token and renews it by itself. Access tokens last one hour; refresh tokens, 30 days, rotated on every use.

• Only an administrator can approve. A professional who signs in is told to ask the account administrator.
• Each connection is a key. It shows up in the dashboard as a connected app, takes the same rate limits and quota, and counts toward the plan’s limit of active keys. Revoking it there cuts the agent off immediately.
• OAuth tokens only work here. A lat_… access token is accepted by /v1/mcp alone; the REST routes answer 401 to it.
• Public clients, PKCE required. Clients identify themselves by a metadata document URL or register dynamically (RFC 7591); no client secret is issued, and only S256 is accepted. Discovery lives at /.well-known/oauth-authorization-server.

Connect with an API key

A client without OAuth — or a server-side integration — sends a regular key as a Bearer token, exactly as on the REST routes. Nothing changed for integrations that already use one. Keep the token in an environment variable and pass it as a header:

claude mcp add --transport http linqo \
  https://v1.uselinqo.com/v1/mcp \
  --header "Authorization: Bearer $LINQO_API_KEY"

The same thing as configuration, for Claude Code and Cursor (Cursor ignores type):

{
  "mcpServers": {
    "linqo": {
      "type": "http",
      "url": "https://v1.uselinqo.com/v1/mcp",
      "headers": { "Authorization": "Bearer bk_prod_<keyId>.<secret>" }
    }
  }
}

The agent only sees the tools the key’s scopes reach — a tool outside them is not listed at all, rather than listed and refused. A read-only key makes an agent that answers questions about the calendar without changing it: a sensible start.

Unlike the rest of the API, a 401 here comes from the endpoint itself: it uses the error envelope (UNAUTHORIZED) and carries WWW-Authenticate. An invalid, expired or revoked token adds error="invalid_token", without saying which.

Tools

Quota is spent by tools/call only, at the cost of the route behind the tool. Listing tools (tools/list) and discovering the server (server/discover) are free.

12 tools, each driving one route. The route is the contract: follow the link to see exactly what a tool reads and writes.

Metadata

curl 'https://v1.uselinqo.com/v1/openapi'

curl 'https://v1.uselinqo.com/v1/meta' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

Services

curl 'https://v1.uselinqo.com/v1/services' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl 'https://v1.uselinqo.com/v1/services/<serviceId>' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl 'https://v1.uselinqo.com/v1/services/<serviceId>/professionals' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

Professionals

curl 'https://v1.uselinqo.com/v1/professionals' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl 'https://v1.uselinqo.com/v1/professionals/<professionalId>' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl 'https://v1.uselinqo.com/v1/professionals/<professionalId>/availability?date=2026-03-14&service_id=<service_id>' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

Clients

curl 'https://v1.uselinqo.com/v1/clients' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl 'https://v1.uselinqo.com/v1/clients/<clientId>' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

Appointments

curl 'https://v1.uselinqo.com/v1/appointments?from=2026-03-14&to=2026-03-21' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl -X POST 'https://v1.uselinqo.com/v1/appointments' \
  -H 'Authorization: Bearer $LINQO_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{
  "professional_id": "<professional_id>",
  "service_ids": [
    "<service_ids>"
  ]
}'

curl 'https://v1.uselinqo.com/v1/appointments/<appointmentId>' \
  -H 'Authorization: Bearer $LINQO_API_KEY'

curl -X PATCH 'https://v1.uselinqo.com/v1/appointments/<appointmentId>' \
  -H 'Authorization: Bearer $LINQO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "scheduled"
}'

Agents (MCP)

curl -X POST 'https://v1.uselinqo.com/v1/mcp' \
  -H 'Authorization: Bearer $LINQO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "method": "<method>"
}'

Models

The resources the routes return and accept. The descriptions come straight from the contract — the same text any integrator reads in /v1/openapi.