Quickstart - Archyon

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.

Sign in at archyon.app.
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.
Open Account → Tokens and click New token.
Provide a descriptive name (for example, quickstart-laptop).
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.

​Prerequisites

​1. Mint a personal access token

​2. Verify the token

​3. List workspaces

​4. Read a workspace in full

​5. Create a component

​6. Create a relationship

​Next steps