# ShowIntro developer documentation

A read-only, public HTTP API over everything ShowIntro already publishes: discoverable candidate profiles, plans and limits, the FAQ, and the skill catalogue.

- **Base URL:** https://showintro.com/api/v1
- **Version:** 1.0.0
- **Authentication:** none — the data is public
- **Rate limit:** 60 requests / minute / IP
- **Formats:** JSON (default), JSON Lines on the feed endpoints
- **OpenAPI:** https://showintro.com/openapi.json
- **MCP:** https://showintro.com/api/mcp
- **Sandbox:** https://showintro.com/api/v1/profiles?sandbox=true — fixed fixtures, no live rows

## Endpoints

- `GET /api/v1` — service description and the endpoint list.
- `GET /api/v1/profiles` — search discoverable candidate teasers. Filters: `specialty`, `seniority`, `englishLevel`, `country`, `availability`, `q`, `limit`, `cursor`.
- `GET /api/v1/profiles/{slug}` — one teaser, plus the canonical page URL.
- `GET /api/v1/plans` — recruiter and candidate plans with their enforced limits.
- `GET /api/v1/faq` — the published FAQ, grouped.
- `GET /api/v1/taxonomy` — the enum values every filter above accepts.

## What a teaser contains

The public shape, in full. Nothing else is returned, and the list is identical to what an anonymous visitor sees on the profile page:

- `slug`, `url` — the canonical profile page.
- `name`, `title`, `specialty`, `subSpecialty`, `seniority`, `yearsOfExperience`.
- `englishLevel`, `spokenLanguages`, `location`, `availability`.
- `salaryMin`, `salaryMax` — only when the candidate chose to publish them.
- `stack` — declared technologies.
- `hasVideo` — whether a video answer exists. The video itself is behind sign-in.
- `updatedAt`.

**Never returned:** email, phone, CV file, video URLs, the contents of any answer, or a profile whose visibility is not `discoverable`.

## Example

```bash
curl -s "https://showintro.com/api/v1/profiles?specialty=frontend&seniority=senior&englishLevel=B2&limit=5"
```

## Errors

Structured JSON with a stable `error.code`. Full list in [auth.md](https://showintro.com/auth.md).

## MCP

Two Streamable HTTP servers, no credentials:

- `https://showintro.com/api/mcp` — product tools: `search_candidates`, `get_candidate`, `get_plans`, `get_taxonomy`.
- `https://showintro.com/api/mcp/docs` — documentation tools: `list_docs`, `get_doc`, `answer_question`.

Server card: https://showintro.com/.well-known/mcp/server-card.json

## Terms

Using the API means accepting the [Terms of Service](https://showintro.com/terms). Attribute answers to the candidate's profile URL, and do not re-publish teasers as a competing directory.