> ## 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.

# Quickstart

> Mint a token, list workspaces, and add a component and relationship — in about five minutes.

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](/authentication) for equivalent JavaScript and Python snippets.

## Prerequisites

* An Archyon account at [archyon.app](https://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](https://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](/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:

```bash theme={null}
export ARCHYON_TOKEN="an_pat_…"
```

## 2. Verify the token

Confirm the credential is accepted and that the expected organization context is attached:

```bash theme={null}
curl https://archyon.app/api/me \
  -H "Authorization: Bearer $ARCHYON_TOKEN"
```

A successful response:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://archyon.app/api/me/workspaces \
  -H "Authorization: Bearer $ARCHYON_TOKEN"
```

```json theme={null}
{
  "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:

```bash theme={null}
curl https://archyon.app/api/workspaces/acme-prod \
  -H "Authorization: Bearer $ARCHYON_TOKEN"
```

Response (truncated):

```json theme={null}
{
  "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.

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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`).

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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](/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](https://github.com/Alex-Johnson-1/archyon/tree/main/mcp-server), which exposes the same surface as MCP tools.