API overview

iyedy's public REST API serves your diagrams, views, checks, dependency graph and proposals to scripts and CI jobs, with a token and its scopes.

The public API is a REST API over HTTPS. A script, a CI job or an agent calls it with a token, and gets JSON back. It reads what your account can read and does what your roles allow, nothing more.

Base address and description

• Base address: https://app.iyedy.com/v1.
• Description: the OpenAPI 3.1 document of every route is at https://app.iyedy.com/v1/openapi.json. Load it in your API tool to browse the routes and their schemas.
• Where you work: most routes sit under an organisation and a workspace, /v1/t/{tenantId}/w/{workspaceId}/…. GET /v1/token tells you both ids for your token: see Your first API call.

What you can do

Scopes and roles add up: a scope opens a route, and your role in the workspace still decides. A cartouche.write scope on a viewer's token writes nothing. See Scopes.

What the API does not do

• No administration. A token never creates tokens, manages members or settings, opens the app's live connection, runs the Assistant or exports a whole library.
• No decision on a proposal. Applying or rejecting a proposal is done in the app, by a person.
• No webhooks and no GitHub app. iyedy does not call your systems; your jobs call iyedy. See Integrations.
• No command-line tool to install yet. See Command-line tool.

Tokens

Every request carries a token in the Authorization: Bearer header. A personal access token (crt_pat_…) acts as you. A service-account token (crt_sa_…) acts as a service account of your organisation, for CI. On a request with a token, a session cookie is ignored. See Create and manage API tokens and Service accounts.

Conventions

• Errors are JSON: an error object with code, message, detail and requestId. A read you are not allowed is answered 404, like something that does not exist. See Rate limits and errors.
• Lists take limit (200 at most) and cursor, and answer the items with a nextCursor.
• Retries: send an Idempotency-Key header on a creating POST; a replay within 24 hours gets the stored answer.
• Versions: changes inside /v1 only add things. A breaking change would come as /v2, with 12 months of overlap and Deprecation and Sunset headers on the old routes.

What this means for you

Use the API to bring iyedy into the tools you already run: export the views your docs show, run the checks in a pipeline, follow what depends on a component before you change it. To change a diagram from a job, prefer a proposal: a person stays in the loop. Start with Your first API call.