API Documentation

Syntaxia Anchor API

RESTful API for managing ontologies, users, and accounts. Every endpoint is under /api/v1. All responses are in JSON format.

Base URL

https://anchor.syntaxia.com

Version

v1

Format

JSON

Authentication

All API requests require authentication using a bearer token. Include your token in the Authorization header of every request.

How to authenticate

1. Get a token by calling /api/v1/auth with your credentials
2. Include the token in every request: Authorization: Bearer YOUR_TOKEN
3. Set Content-Type: application/json for all requests

Example

Request

curl -X POST "https://anchor.syntaxia.com/api/v1/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "otp_attempt": "123456"
  }'

Response ⚠️ Returns 401 if credentials are invalid

{
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

Pagination

List endpoints accept page and per_page query parameters and return a standard pagination envelope.

Query parameters

Param	Default	Description
`page`	1	Page number
`per_page`	25	Results per page

Response envelope

Response

{
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 143,
    "total_pages": 6
  },
  "data": [...]
}

Quickstart

Get started in minutes with these code examples. Select your preferred language below.

1. List your accounts

export TOKEN="your-api-token"

curl "https://anchor.syntaxia.com/api/v1/accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

2. Get current user

curl "https://anchor.syntaxia.com/api/v1/me" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

1. List your accounts

import requests

TOKEN = "your-api-token"
BASE_URL = "https://anchor.syntaxia.com"

response = requests.get(
    f"{BASE_URL}/api/v1/accounts",
    headers={"Authorization": f"Bearer {TOKEN}"}
)
response.raise_for_status()
accounts = response.json()
print(accounts)

2. Get current user

response = requests.get(
    f"{BASE_URL}/api/v1/me",
    headers={"Authorization": f"Bearer {TOKEN}"}
)
response.raise_for_status()
user = response.json()
print(f"User: {user['name']}")

1. List your accounts

const TOKEN = "your-api-token";
const BASE_URL = "https://anchor.syntaxia.com";

async function getAccounts() {
  const response = await fetch(`${BASE_URL}/api/v1/accounts`, {
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    }
  });
  
  if (!response.ok) throw new Error(await response.text());
  const accounts = await response.json();
  console.log(accounts);
}

getAccounts();

2. Get current user

async function getCurrentUser() {
  const response = await fetch(`${BASE_URL}/api/v1/me`, {
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json"
    }
  });
  
  if (!response.ok) throw new Error(await response.text());
  const user = await response.json();
  console.log(`User: ${user.name}`);
}

getCurrentUser();

Ontologies

Create, read, update, and delete ontologies. Ontologies are the core resource in Syntaxia Anchor — versioned definitions that your runtime pipeline reads and manages.

Visibility

public — Visible to any authenticated user.
private — Visible only to members of the owning account.

The API never reveals the existence of a private resource you can't see. A 404 means "not found or not yours."

200 Success 201 Created 401 Unauthorized 404 Not Found 422 Validation Error

GET /api/v1/ontologies

List ontologies visible to you. Supports filtering and pagination.

Param	Description
`filter`	all (default), my_accounts, or public
`source_format`	Filter by format (e.g. yaml, json)
`parent_id`	Filter to children of a specific ontology
`title`	Case-insensitive substring search on title
`page`	Page number (default: 1)
`per_page`	Results per page (default: 25)

Response

{
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 3,
    "total_pages": 1
  },
  "data": [
    {
      "id": "01933abc-1234-7def-a567-89b0cde12345",
      "account_id": "01933abc-0001-7000-a000-000000000001",
      "parent_id": null,
      "title": "Canonical GTM Model",
      "description": "The source of truth for all GTM mappings.",
      "visibility": "public",
      "source": "---\nversion: 1.0.0\n...",
      "source_format": "yaml",
      "version": "1.2.0",
      "head_hash": "sha256:abc123",
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-03-01T14:32:11.000Z",
      "url": "https://anchor.syntaxia.io/api/v1/ontologies/01933abc-..."
    }
  ]
}

GET /api/v1/ontologies/:id

Fetch a single ontology by ID. Returns the ontology object directly — no pagination envelope.

Response

{
  "id": "01933abc-1234-7def-a567-89b0cde12345",
  "account_id": "01933abc-0001-7000-a000-000000000001",
  "parent_id": null,
  "title": "Canonical GTM Model",
  "description": "The source of truth for all GTM mappings.",
  "visibility": "public",
  "source": "---\nversion: 1.0.0\n...",
  "source_format": "yaml",
  "version": "1.2.0",
  "head_hash": "sha256:abc123",
  "created_at": "2025-01-15T10:00:00.000Z",
  "updated_at": "2025-03-01T14:32:11.000Z",
  "url": "https://anchor.syntaxia.io/api/v1/ontologies/01933abc-..."
}

POST /api/v1/ontologies

Create an ontology. This also creates the first commit — the two happen atomically.

Request body

{
  "ontology": {
    "title": "Salesforce Mapping",
    "description": "Maps canonical fields to Salesforce objects.",
    "visibility": "private",
    "source": "---\nversion: 1.0.0\n...",
    "source_format": "yaml",
    "parent_id": "01933abc-1234-7def-a567-89b0cde12345",
    "version": "1.0.0"
  },
  "change_summary": "Initial definition"
}

Response 201 Created

{
  "id": "...",
  "title": "Salesforce Mapping",
  "visibility": "private",
  "version": "1.0.0",
  "head_hash": "sha256:...",
  "..."
}

change_summary is optional — defaults to "Initial commit via API". parent_id is optional; omit it for a root ontology.

PATCH /api/v1/ontologies/:id

Update an ontology. You must be a member of the owning account. Send only the fields you're changing.

Request body

{
  "ontology": {
    "title": "Salesforce Mapping v2",
    "source": "---\nversion: 1.1.0\n...",
    "source_format": "yaml"
  },
  "version_bump": "minor",
  "change_summary": "Add opportunity stage field"
}

Version bumps

version_bump	Effect
patch (default)	1.2.0 → 1.2.1
minor	1.2.0 → 1.3.0
major	1.2.0 → 2.0.0

If source or source_format changes, a new commit is created automatically. Changes to title, description, visibility, or parent_id alone don't create a new commit.

DELETE /api/v1/ontologies/:id

Delete an ontology. You must be a member of the owning account. Returns 204 No Content.

⚠️ This action cannot be undone. All commits associated with this ontology will also be deleted.

GET /api/v1/ontologies/:id/children

List the direct children of an ontology. Only children visible to you are returned.

Param	Description
`source_format`	Filter by format
`page`	Page number (default: 1)
`per_page`	Results per page (default: 25)

Returns a paginated envelope with ontology objects (same shape as the list endpoint).

Commits

Every change to an ontology's source content creates a commit. Commits are immutable and form a linear history.

200 Success 401 Unauthorized 404 Not Found

Commit status

applied — The current head of the ontology; this is what's live.
superseded — A historical commit; a newer one has since been applied.

GET /api/v1/ontologies/:id/commits

List the commit history for an ontology, newest first.

The source field is intentionally absent from list responses to keep payloads small. Use the single commit endpoint to get the full content.

Response

{
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 4,
    "total_pages": 1
  },
  "data": [
    {
      "id": "01933def-5678-7abc-b901-23d4efa56789",
      "commit_hash": "sha256:abc123",
      "message": "Add opportunity stage field",
      "source_format": "yaml",
      "status": "applied",
      "version": "1.1.0",
      "author_id": "01933abc-0002-7000-b000-000000000002",
      "created_at": "2025-03-01T14:32:11.000Z",
      "updated_at": "2025-03-01T14:32:11.000Z"
    }
  ]
}

GET /api/v1/ontologies/:id/commits/:commit_id

Fetch a single commit with its full source content.

The commit must belong to the ontology in the URL. Requesting a valid commit ID under a different ontology returns 404.

Response

{
  "id": "01933def-5678-7abc-b901-23d4efa56789",
  "commit_hash": "sha256:abc123",
  "message": "Add opportunity stage field",
  "source_format": "yaml",
  "status": "applied",
  "version": "1.1.0",
  "author_id": "01933abc-0002-7000-b000-000000000002",
  "source": "---\nversion: 1.1.0\nfields:\n  - name: opportunity_stage\n    type: string\n",
  "created_at": "2025-03-01T14:32:11.000Z",
  "updated_at": "2025-03-01T14:32:11.000Z"
}

User Management

Create and manage user accounts, update profiles, and handle authentication.

200/201 Success 401 Unauthorized 422 Validation Error

POST /api/v1/users

Create a new user account and receive an API token.

Request body

{
  "user": {
    "email": "new@example.com",
    "password": "secure-password",
    "password_confirmation": "secure-password",
    "name": "John Doe"
  }
}

Response

{
  "user": {
    "id": "usr_123",
    "email": "new@example.com",
    "name": "John Doe",
    "api_tokens": [{
      "id": "tok_123",
      "name": "API Token",
      "token": "your-generated-token"
    }]
  }
}

GET /api/v1/me

Get the currently authenticated user's profile.

Response

{
  "id": "usr_123",
  "name": "Ada Lovelace",
  "avatar_url": "https://cdn.syntaxia.io/avatar.png",
  "sgid": "user-sgid",
  "content": "<div>Profile HTML content</div>"
}

PUT /api/v1/password

Update the current user's password.

Request body

{
  "user": {
    "current_password": "old-password",
    "password": "new-password",
    "password_confirmation": "new-password"
  }
}

Response

{
  "success": true
}

DELETE /api/v1/me

Delete the current user account permanently.

⚠️ Returns an empty object on success. This action cannot be undone.

Accounts

Manage workspaces and team accounts. List accounts and view account details.

200 Success 401 Unauthorized 404 Not Found

GET /api/v1/accounts

List all accounts the authenticated user belongs to.

Response

[
  {
    "id": "acc_001",
    "name": "Main Workspace",
    "personal": false,
    "owner_id": "usr_123",
    "created_at": "2024-01-10T12:00:00Z",
    "updated_at": "2024-02-03T16:21:00Z",
    "account_users": [
      {"id": "acu_01", "user_id": "usr_123"}
    ]
  }
]

Notifications

Retrieve and manage user notifications. Mark notifications as read and list all notifications.

200 Success 401 Unauthorized

POST / DELETE /api/v1/notification_tokens

Register or remove push notification tokens (for Hotwire Native apps).

Request body

{
  "token": "device-push-token",
  "platform": "ios"
}

Errors

The API uses standard HTTP status codes and keeps error responses simple.

Status	Meaning
401	Missing or invalid token
404	Resource doesn't exist, or exists but isn't visible to you
422	Validation failed

Validation error example

422 Unprocessable Entity

{
  "errors": {
    "title": ["can't be blank"],
    "source_format": ["is not included in the list"]
  }
}

404 is deliberately ambiguous — you won't learn whether a private resource exists by probing it.