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

Public machine interfaces: address, access and what each gives you
InterfaceAddressAccessWhat it gives you
MCP serverPOST /mcp, card server-card.jsonnoneJSON-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 agentPOST /api/a2a, card agent-card.jsonnonemessage/send: questions about KONDEVS and the Content Hub.
Markdownany page, or its address with .md (/about.md)noneSend 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.
Feedsfeed.xml (RSS), feed.json (JSON Feed)noneThe newest 50 articles in full: key takeaways, body, FAQ, sources.
Site guidesllms.txt, llms-full.txt, sitemap.xmlnoneWhat the site holds, when to use it, every page.
API descriptionsopenapi.json, api-catalog, /api/noneOpenAPI 3.1, the RFC 9727 catalog and a JSON index of every endpoint.
Discoveryai-catalog.json, agent skillsnoneThe ARD catalog and the agent skills index.
HealthGET /api/healthnoneLiveness 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:read or content:write). GET /api/oauth/register returns the same instructions as JSON.
  • Authentication. Authorization: Bearer <key>, or exchange the key for a one-hour token with OAuth 2.0 client_credentials at POST /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 public GET /api/content/version and GET /api/content/{slug} (a published article; a draft with the key). Covers are optional; a create answers the article's url relative 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 --sandbox with KONDEVS_SANDBOX_URL=https://kondevs-sandbox.pages.dev. The key comes from KONDEVS_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/register there 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/token does not exchange it. Point a client at it with servers[1] of openapi.json.
  • Testing without side effects. On the live API, POST /api/content/?dry_run=1 (or "dry_run": true in 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-Key header with POST /api/content/: a retry with the same key and body gets the first answer again (marked Idempotent-Replayed: true) for 24 hours; the same key with a different body answers 422. PUT and DELETE are 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.

Every HTTP endpoint: method and path, access, what it does
EndpointAccessWhat it does
GET /api/noneThis index: every endpoint with its method, access and purpose, and where the docs are.
GET /api/healthnoneLiveness probe.
POST /mcpnoneMCP server (JSON-RPC 2.0, Streamable HTTP): search and read articles, list services, company facts.
POST /api/a2anoneA2A agent (JSON-RPC 2.0, message/send).
GET /api/content/versionnoneContent API version and the rendering capabilities of this site.
GET /api/content/catalogtoken (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/catalogtoken (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}noneOne 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/tagstoken (content:read)The tags of the published articles: the same list as the catalog's.
POST /api/content/imagestoken (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/tokenclientOAuth 2.0 client_credentials: exchange an issued secret for a 1-hour bearer token (RFC 6749 errors).
GET /api/oauth/registernoneHow to obtain credentials (issued by human review, no self-service; the sandbox issues its own test keys).
POST /api/oauth/registernoneProduction: 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/contactnoneThe 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_request HTTP 400
The request is malformed. Check the request against the OpenAPI description at /openapi.json.
validation_failed HTTP 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_version HTTP 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_key HTTP 400
The Idempotency-Key header is not 1-255 visible ASCII characters. Send a unique value per request, for example a UUID.
unauthorized HTTP 401
No valid Bearer key or token. Send Authorization: Bearer <token>. Keys are issued to publishing partners; see /auth.md.
forbidden HTTP 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_found HTTP 404
No endpoint or no article at this address. Check the path. GET /api/ lists the endpoints; /openapi.json describes them.
method_not_allowed HTTP 405
This path does not accept this method. Use one of the methods in the Allow header.
conflict HTTP 409
An article with this slug already exists. Update it with PUT /api/content/{slug}, or publish under another slug.
idempotency_in_progress HTTP 409
A request with this Idempotency-Key is still running. Retry in a few seconds (Retry-After).
payload_too_large HTTP 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_type HTTP 415
The body is not JSON. Send Content-Type: application/json.
idempotency_key_reused HTTP 422
This Idempotency-Key was already used with a different body. Use a new Idempotency-Key for a different request.
rate_limited HTTP 429
Too many requests from this address. Wait for the number of seconds in the Retry-After header, then retry.
internal_error HTTP 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_gateway HTTP 502
An upstream service failed. Retry later. If it persists, write to info@kondevs.com.
unavailable HTTP 503
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

Rate limits per interface
EndpointLimitCounted
POST /mcp120 per minuteper IP
POST /api/a2a60 per minuteper IP
GET /api/content/catalog60 per minuteper IP
POST /api/content/catalog10 per hourper IP
GET /api/content/tags60 per minuteper IP
POST /api/content/30 per hourper IP
PUT /api/content/{slug}30 per hourper IP
DELETE /api/content/{slug}30 per hourper IP
POST /api/content/images120 per hourper IP
POST /api/oauth/token30 per minuteper IP
POST /api/oauth/register30 per minuteper IP
POST /api/contact5 per 10 minutesper 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.

Have a project in mind?

Tell us the objective, and we'll tell you honestly how we would approach it.

The first conversation is free and without obligation.