OpenAPI document

The File Service API is described by one OpenAPI 3 document. Use it to generate a typed client in a language without a CCS library, to try 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: version 1.0, 113 operations. It is served from the root of this site.

The document is generated from the service itself, so it does not drift from the API. This site builds the API reference from the same document.

What is in it

Part	Holds
info	The title (CCS Files API), version and description
servers	The production host, https://files.centralcodestation.com. Operation paths start with /api/v1
tags	Context, Folders, Uploads, Files, Search, Permissions, Shares, Trash, Settings, Audit, Health
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
components.securitySchemes	One scheme, bearer: a JWT in the Authorization header

Every operation carries 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-action	The action the caller needs on the item: view, download, edit, share, delete or approve
x-required-capabilities	The permission key a user needs in the application, on the administration routes
x-error-codes	The error codes the operation can return
x-status	planned on the routes that answer 501 until they are served

Every operation also has externalDocs, a link to the page on this site that explains it.

Generate a client

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.files.centralcodestation.com/openapi.json \
-g java --library native -o files-client-java

C#

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

Python

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

Go

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

TypeScript types

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

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

For Node.js backends, prefer ccs-files-client: it handles tokens, retries, idempotency keys and the whole upload protocol.

A generated client does not fetch tokens. Get one with your language’s HTTP client (a client_credentials call, see Other languages) and pass it as the bearer token.

Pitfalls

• The server URL is the host. Operation paths start with /api/v1; keep the server entry as https://files.centralcodestation.com.
• resource= takes the identifier, https://files.centralcodestation.com/api, never the audience files-api.
• snake_case is intentional. A generator may rename properties to your language’s style; the name on the wire must stay as the document says.
• Every operation can return the error body, for example rate_limited or identity_unavailable. Make your client turn any non-2xx answer into an error you can inspect, and branch on error.
• Do not close the error enum. A new code is not a breaking change: decode error as a string.
• message can be a string or an array. Validation errors list every problem.
• The bytes are not in the document. Upload and download URLs are opaque signed URLs; follow the upload protocol for them, and never add your token to them.
• Regenerate when the API changes. New fields and operations are not breaking, so an old client keeps working.