OpenAPI document

The Chat API is described by one OpenAPI 3 document. Use it to generate a typed client in a language Chat has no SDK for, to check a request in a tool you already use, or to keep your own types in step with the API. This page tells you where to get it, what is in it and how to generate a client without the usual traps.

Download

Download openapi.json. The same file is served from https://docs.chat.centralcodestation.com/openapi.json.

The document is generated from the Chat API itself, so it does not drift from the API. This site publishes the same document it builds the API reference from, and updates it when the API changes. Operations that only Chat’s own web app uses, such as sign-in, are left out.

What is in it

Part	Holds
info	The title, version and support contact.
servers	The production base URL, https://chat.centralcodestation.com/api/v1.
tags	Seven groups: Context, Conversations, Messages, Users, Presence, Notifications and Administration.
paths	Every operation, with parameters, a request body example, response examples and the error responses it can return.
components.schemas	The request and response bodies, with enums and nullability. See Data types.
components.securitySchemes	One scheme, bearer: a JWT in the Authorization header.

Every operation carries four extensions that standard tools ignore:

Extension	Holds
x-audience	Who may call it: user, machine or public.
x-required-scopes	The scope a user token needs, and the machine scopes that grant the operation (any one of them).
x-required-capabilities	The Chat permissions a user needs: all of them, or any one.
x-error-codes	The error codes the operation can return.

They are explained in API conventions. The error field of the error body is an enum with a description for each code, matching the error catalog.

Generate a client

Generate a client from the downloaded file or straight from the address. These commands use the OpenAPI Generator CLI through npx, which needs Node.js; the same generators run from its Docker image or a standalone jar.

Java

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.chat.centralcodestation.com/openapi.json \
  -g java --library native -o chat-client-java

C#

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.chat.centralcodestation.com/openapi.json \
  -g csharp -o chat-client-csharp

Python

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.chat.centralcodestation.com/openapi.json \
  -g python -o chat-client-python

Go

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.chat.centralcodestation.com/openapi.json \
  -g go -o chat-client-go

TypeScript types

If you only want types, use openapi-typescript. It writes a .d.ts file with no runtime code:

npx openapi-typescript https://docs.chat.centralcodestation.com/openapi.json -o chat-api.d.ts

import type { components } from './chat-api';

type Message = components['schemas']['MessageBody'];

For TypeScript clients, prefer the SDKs: they handle tokens, paging and retries.

The generated client does not fetch tokens. Get a token with your language’s HTTP client, then pass it as the bearer token. See Use the REST API from any stack and Other languages.

Pitfalls

• The server URL is the host. Operation paths in the document start with /api/v1, and the server entry is https://chat.centralcodestation.com. Keep it that way when you configure a generated client.
• resource= takes the identifier. When you request a token, pass the Chat API’s resource identifier as resource, not the audience chat-api. The audience is only what you see in the token’s aud claim. See Identity and tokens.
• snake_case is intentional. Every field, query parameter and path parameter is snake_case. A generator may rename properties to your language’s style, which is fine while the name on the wire stays as the document says. Never rename it on the wire.
• Every operation can return the default error body. Besides the listed responses, any operation can answer with the error body, for example rate_limited or identity_unavailable. Make your client turn any non-2xx response into an error you can inspect, and branch on error.
• Do not close the error enum. error lists today’s codes. A new code is not a breaking change, so decode it as a string, or give a closed enum an “unknown” case.
• message can be a string or an array. Validation errors list every problem as an array of strings. Some generators need a hand-written type for this.
• Realtime and push are not in the document. It covers the routes that issue the realtime credential and register push devices, but not the event stream itself. See Realtime events and Push payloads.
• Some operations are for Chat’s web app. The administration routes and /me are in the document, but browsers cannot call them from your origin. See CORS.
• Regenerate when the API changes. New fields and operations are not breaking, so an old client keeps working. Regenerate to get them, and read the platform changelog.