Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archyon.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through the canonical first interactions with the Archyon API: obtaining credentials, reading existing data, and creating new resources. Every example uses curl; see Authentication for equivalent JavaScript and Python snippets.

​
Prerequisites

  • An Archyon account at archyon.app.
  • Membership in at least one organization. Personal accounts that have never joined an organization should create one from the organization switcher in the application header before continuing — organization scope is required for the resources used in this guide.

​
1. Mint a personal access token

Personal access tokens are the recommended credential for any non-browser client.
  1. Sign in at archyon.app.
  2. Switch to the organization the token should act in, using the organization switcher in the top-left of the header. The token is permanently bound to whichever organization is active at mint time — see Authentication › Organization binding.
  3. Open Account → Tokens and click New token.
  4. Provide a descriptive name (for example, quickstart-laptop).
  5. Copy the returned an_pat_… string. The token is shown exactly once; it cannot be recovered later.
Export it as an environment variable for the remainder of this guide: 
export ARCHYON_TOKEN="an_pat_…"

​
2. Verify the token

Confirm the credential is accepted and that the expected organization context is attached: 
curl https://archyon.app/api/me \
  -H "Authorization: Bearer $ARCHYON_TOKEN"
A successful response: 
{
  "id": 42,
  "displayName": "Ada Lovelace",
  "isAdmin": false,
  "provider": "clerk",
  "createdAt": 1716566400000,
  "session": {
    "orgId": "org_2abc...",
    "orgRole": "org:admin",
    "orgSlug": "acme",
    "isApiToken": true
  }
}
If session.orgId is null, the token was minted without an active organization. Switch organizations in the application and re-mint.

​
3. List workspaces

Retrieve every workspace the caller can read in the bound organization: 
curl https://archyon.app/api/me/workspaces \
  -H "Authorization: Bearer $ARCHYON_TOKEN"

{
  "workspaces": [
    {
      "id": "acme-prod",
      "name": "ACME Production",
      "visibility": "org",
      "myRole": "owner",
      "memberSince": 1716566400000,
      "updatedAt": 1716566500000
    }
  ]
}
Pick an id from the result and use it in the next step.

​
4. Read a workspace in full

A single GET returns the workspace metadata together with every component, relationship, stakeholder link, and process it contains: 
curl https://archyon.app/api/workspaces/acme-prod \
  -H "Authorization: Bearer $ARCHYON_TOKEN"
Response (truncated): 
{
  "workspace": {
    "id": "acme-prod",
    "name": "ACME Production",
    "orgId": "org_2abc...",
    "visibility": "org",
    "myRole": "owner",
    "createdAt": 1716000000000,
    "updatedAt": 1716566400000,
    "properties": {}
  },
  "components": [
    {
      "id": "api-gateway",
      "typeId": "service",
      "name": "API Gateway",
      "x": 120,
      "y": 240,
      "properties": {}
    }
  ],
  "relationships": [],
  "stakeholders": [],
  "processes": []
}

​
5. Create a component

Components require a stable id, a typeId from the type catalogue, and a human-readable name. Optional x and y set the canvas position; omitting them places the component at the origin. 
curl -X POST https://archyon.app/api/workspaces/acme-prod/components \
  -H "Authorization: Bearer $ARCHYON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "billing-db",
    "typeId": "database",
    "name": "Billing DB",
    "x": 360,
    "y": 240
  }'

{
  "component": {
    "id": "billing-db",
    "workspaceId": "acme-prod",
    "typeId": "database",
    "name": "Billing DB",
    "description": "",
    "x": 360,
    "y": 240,
    "properties": {}
  }
}
The available typeId values come from GET /api/schema. The default catalogue includes service, database, queue, external, frontend, library, job, and store.

​
6. Create a relationship

Relationships connect two existing components by ID. The typeId again comes from /api/schema (defaults include depends-on, reads-from, writes-to, calls, publishes-to, subscribes-to). 
curl -X POST https://archyon.app/api/workspaces/acme-prod/relationships \
  -H "Authorization: Bearer $ARCHYON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "gw-to-billing",
    "sourceId": "api-gateway",
    "targetId": "billing-db",
    "typeId": "writes-to",
    "label": "writes orders"
  }'

{
  "relationship": {
    "id": "gw-to-billing",
    "workspaceId": "acme-prod",
    "sourceId": "api-gateway",
    "targetId": "billing-db",
    "typeId": "writes-to",
    "label": "writes orders",
    "properties": {}
  }
}
Refresh the workspace in the web application; the new component and edge appear immediately.

​
Next steps

  • Review Conventions for identifier rules, PATCH semantics, and other invariants that apply across all endpoints.
  • Browse the API Reference tab for the complete operation catalogue, including stakeholder links, processes, and the Notion proxy.
  • For programmatic editing from AI tooling, install the Archyon MCP server, which exposes the same surface as MCP tools.