API reference

One endpoint

The event API is a single endpoint. You send it the name of an event and the fields that event needs, and the platform decides from the event itself whether the call needs a credential.

POST /api/v1/platform
X-Site-Id: <your site id>
Content-Type: application/x-www-form-urlencoded

event_type_name=site.stats

Every call holds to the same contract.

• The body is form encoded, not JSON. Fields are flat strings, so anything nested is encoded as a string by the caller.
• X-Site-Id goes on every request. It names the site the call belongs to, and it is not something you send once and forget.
• Authentication is decided per event. Some events are open and the rest need your key, and an event that is unknown or misconfigured is refused rather than let through.

Responses are HTML fragments by default, which is what the product's own screens ask for. Send Accept: application/json and an event whose output is JSON answers in JSON.

Every response carries a trace id in the x-trace-id header. Quote it when you ask us about a call.

Asking what an event expects

Point at an event by name and the platform describes it, with no credential needed.

GET /api/v1/platform/_schema/site.stats

Back comes standard JSON Schema for that event's input, its output schema, whether the event requires authentication, and whether it answers in JSON or with an HTML fragment. Where an event has a schema defined, this is where you read it, and you can read it before you hold a key.

What you can call without a key

Some events are open to anonymous callers, and they cover two kinds of work.

• Reading what a site publishes. Blog posts, forum topics and site statistics are readable without a credential. site.stats is the shortest one to try.
• The account lifecycle. Registering, confirming an email address and requesting a password reset are events on this same endpoint, reached the same way as everything else.

What your key opens

Your key goes in the x-gisdwai-api-key header, and it is what opens an event that requires authentication. Which events your key reaches is set up with you, and the schema endpoint will tell you what each of them expects.

The same key connects your own agents, which Getting started covers.