---
title: "JustIdea Agency developer portal"
description: "Build on justidea.agency: a free, read-only REST API and MCP server with the public pages, services and published starting prices of JustIdea Agency. Quickstart, self-serve access tokens, documentation, limits and testing. No sign-up and no API key."
url: "https://justidea.agency/developers/"
lang: en
---

# JustIdea Agency developer portal

> Search and read the public website of JustIdea Agency, list its services with the published starting prices and get contact options, over a REST API or an MCP server. Free and read-only, with no sign-up and no API key. Your first call takes one line.

- REST API: https://justidea.agency/api/v1 ([OpenAPI 3.1](https://justidea.agency/api/v1/openapi))
- MCP server: https://justidea.agency/mcp
- Self-serve access token: `POST https://justidea.agency/agent/auth/` (optional)
- HTML version of this page: https://justidea.agency/developers/

## Quickstart

### 1. Make your first call, no key needed

```bash
curl "https://justidea.agency/api/v1/search?q=prestashop&lang=en"
curl "https://justidea.agency/api/v1/services?lang=en"
```

Responses are JSON. `GET /api/v1/page?url=<url>` returns one page with its full text as Markdown. Every endpoint, parameter and schema is in the [OpenAPI 3.1 description](https://justidea.agency/api/v1/openapi) (also [as YAML](https://justidea.agency/api/openapi.yaml)).

### 2. Or connect an MCP client

The MCP server at `https://justidea.agency/mcp` speaks Streamable HTTP (JSON-RPC over POST), protocol `2025-11-25` and older. It needs no authentication and keeps no session.

```json
{
  "mcpServers": {
    "justidea": {
      "type": "http",
      "url": "https://justidea.agency/mcp"
    }
  }
}
```

```bash
claude mcp add --transport http justidea https://justidea.agency/mcp
```

Without an SDK, one JSON-RPC request is enough:

```bash
curl -s https://justidea.agency/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_site","arguments":{"query":"PrestaShop migration"}}}'
```

### 3. Optional: get an access token yourself

A token identifies your agent and raises the REST API limit from 120 to 600 requests per minute. One request, no account, no e-mail, no approval:

```bash
curl -s -X POST https://justidea.agency/agent/auth/ \
  -H "Content-Type: application/json" \
  -d '{"type":"anonymous"}'
```

Send `credential` from the response as a bearer token, to the API or to the MCP server, and check who you are:

```bash
curl -s https://justidea.agency/api/v1/identity \
  -H "Authorization: Bearer <credential>"
```

## Access, keys and limits

|  | Without a token | With a token |
|---|---|---|
| Rate limit (REST API) | 120 requests per 60 seconds per IP address | 600 requests per 60 seconds per agent |
| How to get it | Nothing to do | `POST /agent/auth/`, one request |
| Lifetime | Always on | Access token 1 hour, identity assertion 30 days |
| Scope | Every endpoint and tool | The same: `site:read` |

- **API keys are not issued.** The self-serve token replaces them: there is nothing to apply for and no one to e-mail.
- **Renewing:** when the access token expires, exchange the `identity_assertion` at `POST /oauth/token/` instead of registering again. Step by step in [auth.md](https://justidea.agency/auth.md).
- **Revoking and rotating:** tokens are signed and self-contained, and nothing is stored on our side, so there is nothing to revoke. Stop using a token and it expires within an hour.
- **MCP clients acting for a person** (Claude, ChatGPT, Cursor): OAuth 2.1 authorization code with PKCE and open dynamic client registration. Metadata: [protected resource](https://justidea.agency/.well-known/oauth-protected-resource/mcp) (RFC 9728) and [authorization server](https://justidea.agency/.well-known/oauth-authorization-server) (RFC 8414).
- **No accounts and no personal data:** registration asks for nothing and stores nothing.

## Reference

### REST API

Base URL `https://justidea.agency/api/v1`, version 1. Every GET also answers HEAD. CORS is open, so the API works from a browser too.

| Method | Path | Returns |
|---|---|---|
| GET | `/api/v1` | API description with every endpoint URL |
| GET | `/api/v1/health` | Health: version, number of pages, languages |
| GET | `/api/v1/search?q=&lang=&type=&limit=` | Pages matching a query |
| GET | `/api/v1/pages?type=&lang=&limit=&cursor=` | Pages with cursor pagination |
| GET | `/api/v1/page?url=` | One page as Markdown |
| GET | `/api/v1/services?lang=` | Services with published starting prices (PLN or EUR) |
| GET | `/api/v1/contact?lang=` | E-mail, phone and contact page |
| GET | `/api/v1/identity` | The agent behind the bearer token (token required) |
| POST | `/api/v1/batch` | Up to 10 GET operations in one request |

### MCP tools

Server `https://justidea.agency/mcp`, version 1.1.0. These tools are annotated read-only:

| Tool | What it does |
|---|---|
| `list_services` | List JustIdea Agency services with the published starting ("from") prices and links. |
| `get_page` | Full text of one justidea.agency page as Markdown: a service, a price list, the company profile, reviews, a blog article. |
| `search_site` | Search justidea.agency pages by titles, descriptions and section headings. |

`send_inquiry` is not read-only: it passes a person's inquiry to the sales team. Call it only when the user asks to get in touch, with their own contact details and explicit consent.

`scan_analytics` and `scan_ai_visibility` run a free scan of the user's own website (analytics and tracking, or visibility in AI assistants). They need the user's e-mail and explicit consent: you get the grade and the list of problems, and the full report with fixes is e-mailed to the user. Limit: 2 scans per e-mail address per day. `get_scan_result` returns the result of a scan that took longer than one call.

### MCP resources

- `https://justidea.agency/llms.txt`: the site map for language models.
- `https://justidea.agency/pricing.md`: published starting prices in Markdown.

## Documentation

- [OpenAPI 3.1 description](https://justidea.agency/api/v1/openapi): every endpoint, parameter and response schema.
- [API guide](https://justidea.agency/api.md) (Markdown): authentication, rate limits, pagination, batch, versioning and error codes.
- [auth.md](https://justidea.agency/auth.md): agent registration and OAuth, step by step.
- [MCP server card](https://justidea.agency/.well-known/mcp/server-card.json): tools, resources and capabilities of the MCP server.
- [API catalog](https://justidea.agency/.well-known/api-catalog) (RFC 9727) and [AI catalog](https://justidea.agency/.well-known/ai-catalog.json): everything this site offers to agents.
- [Agent Skills index](https://justidea.agency/.well-known/agent-skills/index.json): ready-made skills for agents.
- [llms.txt](https://justidea.agency/llms.txt): the site explained for language models. [Prices as Markdown](https://justidea.agency/pricing.md).
- NLWeb 0.55: `POST /ask` answers a natural-language question with schema.org results (JSON, or Server-Sent Events with `prefer.streaming`). The Schema Map at `/schemamap.xml` lists the structured data of the whole site as one JSONL feed.
- [Entry in the official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers/agency.justidea%2Fjustidea-agency/versions/latest) (`agency.justidea/justidea-agency`) and [listing on Smithery](https://smithery.ai/servers/xawierek/justidea-agency) (`xawierek/justidea-agency`).
- Any page as Markdown: send `Accept: text/markdown`, or replace the trailing slash with `.md`. This portal too: [/developers/index.md](https://justidea.agency/developers/index.md).

## Testing and sandbox

There is no separate sandbox or test mode, and you do not need one. Every REST endpoint and every MCP tool except `send_inquiry` and the scan tools only reads the public website, has no side effects and is safe to call and retry as often as the rate limit allows. Test against production: the same URLs you will use live.

- Health check: [API health](https://justidea.agency/api/v1/health) reports the version and the number of pages.
- Try it in a browser: [search](https://justidea.agency/api/v1/search?q=prestashop&lang=en), [services and prices](https://justidea.agency/api/v1/services?lang=en), [contact options](https://justidea.agency/api/v1/contact?lang=en), [one page](https://justidea.agency/api/v1/page?url=/en/).
- MCP Inspector: `npx @modelcontextprotocol/inspector`, transport Streamable HTTP, URL `https://justidea.agency/mcp`.
- Error handling: `/api/v1/search` without `q` gives `400 invalid-parameter`, an unknown endpoint gives `404 not-found`, and a bad token gives `401 invalid-token` with `WWW-Authenticate`.

## Errors and versioning

- Errors are `application/problem+json` (RFC 9457) with a stable, machine-readable `code`. All codes: [api.md](https://justidea.agency/api.md).
- Every API response carries `RateLimit-Policy` and `X-RateLimit-Limit`; a `429` carries `Retry-After` in seconds.
- The major version is in the path (`/api/v1`). Changes within v1 are additive only. A deprecated version gets a `Deprecation` header, and a `Sunset` header at least 90 days before removal.

## What the API does not do

The REST API never submits forms, books meetings, sends messages or takes payments, and it holds no client data. It returns only prices published on the website: net starting prices, the final quote depends on scope. When a person wants to get in touch, give them the link, e-mail address or phone number from `GET /api/v1/contact`.

## Support

- E-mail: [contact@justidea.agency](mailto:contact@justidea.agency). For a bug in the API or the MCP server, include the request and the response.
- People, not agents, who want to talk about a project: [contact page](https://justidea.agency/en/contact/) or +48 12 400 40 40.