SuGu.

API discovery

This platform is built for humans and agents.

A metadata-driven application platform. One YAML document defines an application: its tables, fields and relations. Every environment generates a user interface and a REST API from that document.

The YAML document is the product. To change what an application is you rewrite the document and a new version is created; there is no endpoint that adds a table or a field.

You need an API key

Everything below this page is authenticated. Only the marketing frontpage and this page are public. 

Authorization: Bearer sugu_<environment>_<secret>

A human creates the key in the console, under the application it belongs to. Keys cannot create keys, so an agent cannot mint its own credential or widen its own role.

Without one, every endpoint answers UNAUTHORIZED.

Then start here

A key does not tell you which application it belongs to. This one call does, and it links to every document the key may read. 

GET https://www.sugu.es/api/v1/_me

Endpoints

{slug} and {env} come from the response to _me. Nothing on this page names an application: which ones exist is not public information.

GET https://www.sugu.es/api/v1/_me

Which application and environment this key belongs to, what its role may do, and a link to every document it may read. Call this first: the token embeds an environment id, not a slug, so no other URL can be constructed without it.

GET https://www.sugu.es/api/v1/_docs/metadata.md

The YAML contract every application is written in: the options at each level, the field types, and a complete annotated example. Read this before proposing metadata. Also available as metadata.json.

GET https://www.sugu.es/api/v1/{slug}/{env}/_docs/agents.md

A brief for the runtime API of one environment, filtered to what this key may call, in prose rather than schema. Explains the loops that OpenAPI cannot.

GET https://www.sugu.es/api/v1/{slug}/{env}/_docs/openapi.json

OpenAPI 3.1 for the runtime API: the generated tables of one environment, as CRUD endpoints. Describes only what this key may call.

GET https://www.sugu.es/api/v1/{slug}/{env}/_meta/schema

The generated schema of one environment — tables, fields, types and relations — as data rather than as an API description.

GET https://www.sugu.es/api/v1/{slug}/_admin/_docs/agents.md

A brief for the backoffice API: reading and rewriting the metadata, versions, environments, backups and hooks. Filtered to this key, and it names what the key may not do as well as what it may.

GET https://www.sugu.es/api/v1/{slug}/_admin/_docs/openapi.json

OpenAPI 3.1 for the backoffice API. Each operation carries x-capability, and x-environments where the capability is scoped to particular environments.

Conventions

  • Every response is {"data": …} or {"error": {"code", "message", …}}. The code is the contract; the message follows the reader's locale and must never be branched on.
  • Sixty requests per minute per key, shared across both API surfaces. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining — pace yourself by those headers rather than by counting.
  • The API is versioned in the path. Everything below is v1.

Error codes

The full vocabulary of both API surfaces, published here so you can recognise a refusal before you make your first call. Branch on the code, never on the message.

Code HTTP Meaning, and what to do
UNAUTHORIZED 401 The bearer token is missing, malformed or expired. Stop and ask a human for a new key; retrying will not help.
FORBIDDEN 403 This key may not perform this operation at all. Stop and report it rather than retrying.
FORBIDDEN_CAPABILITY 403 The key's role lacks a capability. The `capability` and `action` fields name it, and `environment` names where it was needed. Report exactly that to a human instead of retrying.
NOT_FOUND 404 The resource does not exist, or this key cannot see it. Re-read the parent collection before assuming it was deleted.
VALIDATION_FAILED 422 The payload does not satisfy the schema. Read `error.fields`, correct the named fields and send again.
FIELD_FORBIDDEN 422 One or more fields in the payload may not be written by this role. Remove them and resend; the remaining fields are still accepted.
INTEGRITY_VIOLATION 409 The operation breaks a required relation — usually a delete with dependants, or a reference to a record that does not exist. Resolve the relation first.
DEGRADED 402 The environment is degraded, normally for billing reasons. Nothing an agent can do; report it.
QUOTA_EXCEEDED 402 The account that owns this application has used up an allowance. `allowance` names which one, with `limit` and `used` beside it. There is nothing an agent can do: the owner has to wait for the period to renew, buy a budget reset, or upgrade the plan. Report it instead of retrying.
MAINTENANCE 503 A queued operation is rewriting this environment. Writes are refused until it finishes. Poll the environment until its status leaves `onderhoud`, then retry.
ENVIRONMENT_BUSY 409 Another operation already holds this environment. Wait for it rather than starting a second one.
METADATA_INVALID 422 The YAML is not a valid metadata document. `issues` carries a line, a code, a path and a message per problem; branch on `code`. Fix them and validate again before writing.
STALE_BASE_VERSION 409 Someone else wrote a new version since the one named in `base_version`. Re-read the metadata, reapply the change on top of it and send again — do not force.
OPERATION_FAILED 500 A queued operation failed. The reason is in the audit log, not in this response.
CONFLICT 409 The request contradicts the current state of the resource. Re-read it before deciding what to do.