Developers

Quickstart

Read a page as markdown, list the endpoints, search the articles, and check an article without writing it:

curl -H "Accept: text/markdown" https://necto-consulting.pages.dev/
curl https://necto-consulting.pages.dev/api/
curl -X POST https://necto-consulting.pages.dev/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_articles","arguments":{"query":"<your question>"}}}'
curl -X POST "https://necto-consulting.pages.dev/api/content/?dry_run=1" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"slug":"a-test","title":"A test","body":"<p>Text</p>","rubric":"<a category>"}'

Public interfaces

Content API

JSON over HTTPS. A success answers { "status": "ok", "version": ... }; GET /api/ returns this table as JSON, and openapi.json describes every request and answer.

Keys and the sandbox

Tokens are issued by a person, not by an endpoint: write to info@necto-consulting.com with your organisation, what you are building, the expected volume and whether you need to read or to write. There is no self-service registration.

There is no separate test environment. dry_run is the only sandbox: send ?dry_run=1 or "dry_run": true with a create or an update, and the whole payload is validated and the answer says what would be created, or what the article would become, while nothing is written.

A create, an update or a dry run that succeeds may also carry warnings: what the article misses of the body contract that makes a page citable (an answer in its first 60 words, absolute dates instead of "recently", a source for every superlative, sections that read on their own, three questions a client would ask). They are advice: the answer stays 200. A body longer than 100000 characters is stored without the check, and one warning, unchecked, says so.

Errors

Every /api/* error has one shape; errors[] appears when there are several problems. OAuth answers its own RFC 6749 errors and JSON-RPC answers inside its envelope.

{
  "status": "error",
  "code": "validation_failed",
  "message": "The payload failed validation.",
  "hint": "errors[] names each field and what it needs; fix them all and send again.",
  "docs": "https://necto-consulting.pages.dev/developers/#error-validation_failed",
  "errors": [
    {
      "field": "title",
      "message": "required"
    }
  ]
}

Limits

Per client address, in a fixed window. Every answer of a limited endpoint carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) and X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds); a refused request answers 429 with Retry-After in seconds.

An article with its images must stay under 12 MB.

Retrying a create safely

Send Idempotency-Key: <a unique value> with POST /api/content/ (draft-ietf-httpapi-idempotency-key-header). The same key with the same body returns the first answer for 24 hours, marked Idempotent-Replayed: true; the same key with another body answers 422 idempotency_key_reused; a request still running answers 409 with Retry-After. A 5xx or a 429 is not stored, so its retry runs again, and a dry run is never stored.

Versions and deprecation

This is version 1.1.0 of the Content API; every answer says so in X-Content-API-Version. Send X-Content-API-Version: 1 to lock the major version: a request for another one answers 400 unsupported_version before anything runs. A breaking change gets a new major version. Before an endpoint is removed it carries Deprecation and Sunset headers for at least 90 days, and it is listed here.

No endpoint is deprecated.