Developers
Machine-readable access to KONDEVS: the MCP server, markdown pages, feeds and the Content API, with errors, limits and versioning documented.
KONDEVS is an integration, BPM and AI consultancy. This site is built to be read and used by AI agents as well as people: everything below is live, and most of it needs no key.
Quickstart: no key needed
List the tools of the MCP server, then search the articles:
curl -s https://www.kondevs.com/mcp -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -s https://www.kondevs.com/mcp -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_articles","arguments":{"query":"webMethods","limit":3}}}'
Read any page as markdown, or list the HTTP endpoints:
curl -s https://www.kondevs.com/services/eai-integration/ -H "Accept: text/markdown"
curl -s https://www.kondevs.com/services/eai-integration.md
curl -s https://www.kondevs.com/api/
Public interfaces
| Interface | Address | Access | What it gives you |
|---|---|---|---|
| MCP server | POST /mcp, card server-card.json | none | JSON-RPC 2.0 over Streamable HTTP. Tools: search_articles, get_article, list_services, get_company_info. Listed in the official MCP Registry as com.kondevs/content-hub. |
| A2A agent | POST /api/a2a, card agent-card.json | none | message/send: questions about KONDEVS and the Content Hub. |
| Markdown | any page, or its address with .md (/about.md) | none | Send Accept: text/markdown, or ask for the .md address: YAML frontmatter and the page content, no site chrome. An unknown address answers 404 in markdown too. |
| Feeds | feed.xml (RSS), feed.json (JSON Feed) | none | The newest 50 articles in full: key takeaways, body, FAQ, sources. |
| Site guides | llms.txt, llms-full.txt, sitemap.xml | none | What the site holds, when to use it, every page. |
| API descriptions | openapi.json, api-catalog, /api/ | none | OpenAPI 3.1, the RFC 9727 catalog and a JSON index of every endpoint. |
| Discovery | ai-catalog.json, agent skills | none | The ARD catalog and the agent skills index. |
| Health | GET /api/health | none | Liveness probe. |
Content API for publishing partners
The Content API publishes, updates and removes Content Hub articles. It serves content partners such as the VISIBILIO platform; it is not an open, self-service API.
- API keys. On the live site there is no self-service sign-up (the sandbox below issues its own test keys). KONDEVS issues keys to vetted partners: write to info@kondevs.com with your organisation, the integration purpose, the expected volume and the scope you need (
content:readorcontent:write).GET /api/oauth/registerreturns the same instructions as JSON. - Authentication.
Authorization: Bearer <key>, or exchange the key for a one-hour token with OAuth 2.0client_credentialsatPOST /api/oauth/token(ES256, keys at jwks.json). The full guide is auth.md. - Endpoints.
GET /api/content/catalog,GET /api/content/tags,POST /api/content/,PUT /api/content/{slug},DELETE /api/content/{slug},POST /api/content/images(one image, multipart), and the publicGET /api/content/versionandGET /api/content/{slug}(a published article; a draft with the key). Covers are optional; a create answers the article'surlrelative to the site. Schemas and examples are in openapi.json. - SDK and CLI. @kondevs/content on npm wraps every operation of openapi.json (Node 18 or newer, no dependencies):
npx @kondevs/content get what-is-eai,publish article.json --dry-run, and--sandboxwithKONDEVS_SANDBOX_URL=https://kondevs-sandbox.pages.dev. The key comes fromKONDEVS_API_KEY. - Sandbox. kondevs-sandbox.pages.dev runs the same API on its own store, never on kondevs.com, with test data that may be deleted at any time.
POST /api/oauth/registerthere answers a write key at once, valid 7 days (5 per hour per address); its pages are noindex. The key is a direct Bearer key (Authorization: Bearer <key>), not an OAuth client credential:/api/oauth/tokendoes not exchange it. Point a client at it withservers[1]of openapi.json. - Testing without side effects. On the live API,
POST /api/content/?dry_run=1(or"dry_run": truein the body) runs authentication, limits and the full validation and stores nothing, so it is the safe way to test a payload. The answer says what would be created:slug,url,status_after; a slug that is taken answers 409, as a real POST would. - Content advice. A successful create, update or dry run may carry
warnings: the AEO body contract (a relative date, a superlative with no source in its sentence, no answer in the first 60 words, a section that opens with a back-reference, no buyer question at all). Advice only: the article is stored all the same, and a clean body carries none. - Safe retries. Send an
Idempotency-Keyheader withPOST /api/content/: a retry with the same key and body gets the first answer again (markedIdempotent-Replayed: true) for 24 hours; the same key with a different body answers 422.PUTandDELETEare idempotent by definition.
curl -s -X POST "https://www.kondevs.com/api/content/?dry_run=1" \
-H "Authorization: Bearer $KONDEVS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c0b8e-2d4a-4f7e-9a51-3c2e8d7b1a90" \
-d @article.json
All endpoints
The same list as GET /api/ and the paths of openapi.json: all three are built from one table.
| Endpoint | Access | What it does |
|---|---|---|
GET /api/ | none | This index: every endpoint with its method, access and purpose, and where the docs are. |
GET /api/health | none | Liveness probe. |
POST /mcp | none | MCP server (JSON-RPC 2.0, Streamable HTTP): search and read articles, list services, company facts. |
POST /api/a2a | none | A2A agent (JSON-RPC 2.0, message/send). |
GET /api/content/version | none | Content API version and the rendering capabilities of this site. |
GET /api/content/catalog | token (content:read) | Published articles, categories and tags, 100 articles a page unless ?limit= says otherwise (at most 500); next_cursor and a Link rel="next" header name the same next page. |
POST /api/content/catalog | token (content:write) | Rebuild the article lists and counts from the stored articles after parallel writes: a dry run answering each change (changes[]) and the catalog it leaves; ?apply=1 writes them. |
POST /api/content/ | token (content:write) | Publish an article; covers are optional; dry_run validates without storing (a taken slug answers 409); accepts Idempotency-Key. |
GET /api/content/{slug} | none | One article: 200 when it is published, 404 when there is none; a draft answers 200 only with a content key. |
PUT /api/content/{slug} | token (content:write) | Update an article: each field the payload sends replaces the stored one, a field it leaves out keeps its value (the FAQ, key takeaways and sources too; an empty list clears one). |
DELETE /api/content/{slug} | token (content:write) | Unpublish an article. |
GET /api/content/tags | token (content:read) | The tags of the published articles: the same list as the catalog's. |
POST /api/content/images | token (content:write) | Upload one image for an article (multipart/form-data: file, slug, variant; at most 10 MB); the answer names its URL. dry_run checks without storing. |
POST /api/oauth/token | client | OAuth 2.0 client_credentials: exchange an issued secret for a 1-hour bearer token (RFC 6749 errors). |
GET /api/oauth/register | none | How to obtain credentials (issued by human review, no self-service; the sandbox issues its own test keys). |
POST /api/oauth/register | none | Production: answers like GET, registration is manual, no client is created and no credential is issued. On the sandbox server (kondevs-sandbox.pages.dev) a key is issued: 201, a test write key valid 7 days. |
POST /api/contact | none | The contact form of /contacts/ (CSRF token, honeypot, consent, rate limit; Turnstile only when configured); answers { success, message }. While outbound mail is not configured it answers success: false and names info@kondevs.com. |
Errors
Every /api/* error is JSON with a stable code, what went wrong (error on a Content API answer, message on the authentication and limit answers), a hint and, as docs, the code's own entry below. A validation failure lists every field at once in errors (and details, the same list), each { field, message }.
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"status": "error",
"code": "not_found",
"message": "No API endpoint at /api/nope.",
"hint": "Check the path. GET /api/ lists the endpoints; /openapi.json describes them.",
"docs": "https://www.kondevs.com/developers/#error-not_found"
}
bad_requestHTTP 400- The request is malformed. Check the request against the OpenAPI description at /openapi.json.
validation_failedHTTP 400- The payload failed validation; errors[] names each field. Fix the fields listed in
errors; the payload schema is in /openapi.json. Add ?dry_run=1 to validate without storing. unsupported_versionHTTP 400- The X-Content-API-Version header asks for a major version this server does not serve. Send X-Content-API-Version: 1, or leave the header out.
invalid_idempotency_keyHTTP 400- The Idempotency-Key header is not 1-255 visible ASCII characters. Send a unique value per request, for example a UUID.
- No valid Bearer key or token. Send Authorization: Bearer <token>. Keys are issued to publishing partners; see /auth.md.
forbiddenHTTP 403- The key or token is valid but does not carry the scope this call needs. Writes need content:write, the catalog content:read (write includes read); see /auth.md.
not_foundHTTP 404- No endpoint or no article at this address. Check the path. GET /api/ lists the endpoints; /openapi.json describes them.
method_not_allowedHTTP 405- This path does not accept this method. Use one of the methods in the Allow header.
conflictHTTP 409- An article with this slug already exists. Update it with PUT /api/content/{slug}, or publish under another slug.
idempotency_in_progressHTTP 409- A request with this Idempotency-Key is still running. Retry in a few seconds (Retry-After).
payload_too_largeHTTP 413- The body is larger than the limit. Send a smaller body: an article payload may be at most 30 MB, images included.
unsupported_media_typeHTTP 415- The body is not JSON. Send Content-Type: application/json.
idempotency_key_reusedHTTP 422- This Idempotency-Key was already used with a different body. Use a new Idempotency-Key for a different request.
rate_limitedHTTP 429- Too many requests from this address. Wait for the number of seconds in the Retry-After header, then retry.
internal_errorHTTP 500- The server failed. Retry the same request later. A write cut short may be half done: a create answers its retry with 409 and lists the stored article then; GET /api/content/catalog lists what is published. If it persists, write to info@kondevs.com.
bad_gatewayHTTP 502- An upstream service failed. Retry later. If it persists, write to info@kondevs.com.
- The service is not available. Retry later. If it persists, write to info@kondevs.com.
Two protocols keep their own format: the OAuth endpoints answer as RFC 6749 defines (error, error_description), and /mcp and /api/a2a answer JSON-RPC 2.0 errors.
Rate limits
| Endpoint | Limit | Counted |
|---|---|---|
POST /mcp | 120 per minute | per IP |
POST /api/a2a | 60 per minute | per IP |
GET /api/content/catalog | 60 per minute | per IP |
POST /api/content/catalog | 10 per hour | per IP |
GET /api/content/tags | 60 per minute | per IP |
POST /api/content/ | 30 per hour | per IP |
PUT /api/content/{slug} | 30 per hour | per IP |
DELETE /api/content/{slug} | 30 per hour | per IP |
POST /api/content/images | 120 per hour | per IP |
POST /api/oauth/token | 30 per minute | per IP |
POST /api/oauth/register | 30 per minute | per IP |
POST /api/contact | 5 per 10 minutes | per IP |
Rate-limited responses carry RateLimit-Policy and RateLimit (the IETF RateLimit header fields: quota, window, remaining, seconds to reset) and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). A 429 adds Retry-After in seconds.
Versioning and deprecation policy
The Content API is at version 1.1.0: every Content API response carries X-Content-API-Version, and GET /api/content/version returns it with the rendering capabilities of this site. Changes within major version 1 only add fields. A client can pin the major version with X-Content-API-Version: 1 (also 1.1, v1); a request for another major version is refused with 400 unsupported_version before anything runs. A breaking change gets a new major version. Anything that is going to be removed will be announced on this page and with Deprecation and Sunset response headers for at least 90 days before it goes. Nothing is deprecated today.
Questions
Write to info@kondevs.com. For what KONDEVS does and when to call on it, read llms.txt.