# Docs for Agents and Developers | Koso

> How software can talk to koso.ai: the public HTTP API, the read-only MCP server and A2A agent, Markdown versions of every page, and the discovery files.

[Skip to content](#main)

[](/)

[Services](/services)[AI OS](/ai-os)[Training](/training)[Education](/education)[Agents](/agents)[Learn](/learn)

…

[Book a call ](/book)

# Docs for agents and developers

Everything on koso.ai that software can read or call, and how to call it. None of it needs a key.

Contents

1. [Where to start](#discovery)
2. [Pages as Markdown](#markdown)
3. [HTTP API](#http-api)
4. [MCP server](#mcp)
5. [A2A agent](#a2a)
6. [Rate limits and auth](#limits)

## Where to start

If you're an agent landing here cold, read </llms.txt> first. It lists every page with a one-line summary. Everything else below is linked from it or from </robots.txt>.

| File                                   | What it is                                                                          |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| </llms.txt>                            | Content index in Markdown                                                           |
| </sitemap.xml>                         | Every public page                                                                   |
| </openapi.json>                        | The public HTTP API, as OpenAPI                                                     |
| </auth.md>                             | What needs credentials (almost nothing) and what doesn't                            |
| </.well-known/api-catalog>             | RFC 9727 API catalog                                                                |
| </.well-known/agent-card.json>         | A2A agent card                                                                      |
| </.well-known/mcp/server-card.json>    | MCP server card                                                                     |
| </.well-known/agent-skills/index.json> | Agent Skills for booking a call, applying to a role and summarising Koso's services |

## Pages as Markdown

Any marketing page on koso.ai can be fetched as Markdown instead of HTML. Ask with an `Accept: text/markdown` header, or add `.md` to the path. Known AI crawlers such as GPTBot and ClaudeBot get Markdown automatically.

curl -H "Accept: text/markdown" https://koso.ai/about
curl https://koso.ai/about.md

The booking, careers and meetings apps under `/book`, `/careers` and `/meetings` are client-rendered, so they have no Markdown version. Use the API for those instead.

## HTTP API

No API key, no account. The full schema is in </openapi.json>.

| Method | Path                                     | Does                                        |
| ------ | ---------------------------------------- | ------------------------------------------- |
| GET    | /api/healthz                             | Liveness check                              |
| GET    | /api/consultations/slots?date=YYYY-MM-DD | Free 30-minute consultation slots on a date |
| POST   | /api/consultations                       | Books a consultation                        |
| GET    | /api/careers/jobs                        | Published open roles                        |
| GET    | /api/careers/jobs/{slug}                 | One role, with its screening questions      |
| POST   | /api/careers/jobs/{slug}/apply           | Submits an application                      |
| POST   | /api/contact                             | Sends a contact message                     |

The three POST endpoints email a real person, and booking also puts an event on a calendar. Only call them when a human has asked you to, with their own details. To check the API is up, use `/api/healthz`.

Consultations run Tuesday to Friday, 12:00 to 16:00 IST. Any other day returns an empty list, which isn't an error.

## MCP server

`POST https://koso.ai/mcp`, streamable HTTP, stateless, no auth. It's read-only on purpose. Booking and applying stay on the HTTP API above.

| Tool                     | Does                                       |
| ------------------------ | ------------------------------------------ |
| get\_consultation\_slots | Free slots for a YYYY-MM-DD date           |
| list\_open\_roles        | Published roles, newest first              |
| get\_role                | One role by slug, with screening questions |

## A2A agent

`POST https://koso.ai/a2a/v1/message:send`, protocol version 1.0\. Send an `A2A-Version: 1.0` header. Without it the server assumes 0.3 and answers `VERSION_NOT_SUPPORTED`. The agent answers the same read-only questions as the MCP server, and its skills are listed in </.well-known/agent-card.json>.

## Rate limits and auth

Limits are per IP. MCP and A2A share a budget of 120 requests an hour, and form submissions are capped at 15 an hour. Going over returns `429` with a `Retry-After` header. Back off rather than rotating addresses.

Paths under `/api/admin/` need a staff token and aren't for third parties. If you hit a `401` there, stop. </auth.md> has the details.

Need more volume, or something these endpoints don't cover? [Get in touch](/contact) and a person will answer.

A custom AI development agency. Bespoke agents, copilots and products engineered for teams that want a moat, not a subscription.

Ideanab Private Ltd is a company registered in England and Wales, no. [16344048](https://find-and-update.company-information.service.gov.uk/company/16344048). Registered office: 124 City Road, London, EC1V 2NX, United Kingdom.

### Company

* [Services](/services)
* [Custom AI Agency](/custom-ai-agency)
* [AI Product Development](/ai-product-development)
* [AI OS](/ai-os)
* [AI Engineering](/ai-engineering-company)
* [AI Consulting](/ai-consulting-company)
* [AI Consulting Services](/artificial-intelligence-consulting-services)
* [Training](/training)
* [Education](/education)
* [Free AI Agents](/agents)
* [Learn AI](/learn)
* [Fractional CAIO](/caio)
* [About Us](/about)
* [The Koso Deck](/deck)
* [Careers](/careers)
* [Docs for agents](/docs)

### Contact

* [Contact us](/contact)
* [Book a call](/book)
* [LinkedIn](https://www.linkedin.com/company/koso)
* [Instagram](https://www.instagram.com/okaashish)

### Legal

* [Terms of Service](/terms)
* [Privacy Policy](/privacy)
* [Cookie Policy](/cookies)
* [Acceptable Use Policy](/acceptable-use)

© 2026 Koso, a brand of Ideanab Private Ltd. All rights reserved.