API Overview

The Aplas v3 API lets you read and write the same data you see in the app — workspaces, asset types, assets, relations, views and publications — over HTTPS using JSON.

Base URL

Aplas is hosted in three regions. Use the URL that matches where your organization's data lives:

Each region is self-contained. An API key issued in the Australia region will not work against the Europe or US endpoints.

Your organization is provisioned in a single region. To check yours, open the Config dashboard in Aplas — the Data residency card shows your region and API endpoint.

Authentication

All requests require an API key, sent as a bearer token in the Authorization header:

curl https://api.au.aplas.com/api/v3/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

To create an API key, sign in to Aplas and open Config → API to generate a new key. Keys are scoped to the organization and region they were created in. Treat them like passwords — they grant access to your organization's data.

Key roles

Each key carries one of two roles, chosen when you create it:

Give integrations that only report on your estate a ReadOnly key. It cannot damage anything even if it is misconfigured or leaked.

When a call is refused

Two different failures are easy to confuse, so they use different statuses:

A 401 means try different credentials. A 403 means these credentials will never work for this, so retrying is pointless.

Responses and errors

Every list endpoint returns the same envelope, so paging code works against any of them:

{
  "data": [ /* the page of resources */ ],
  "nextCursor": "eyJpZCI6..."
}

Single-resource endpoints return the resource itself, unwrapped.

Errors share one shape:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "The permissions of your API key only allow read-only/GET calls."
}

message is written to be shown to a person or read by a model — it names the field, the option or the limit that was wrong wherever it can.

Identifiers

Every resource is addressed by its slug, returned as id. A slug is unique within your organization, is chosen when the resource is created, and does not change when the resource is renamed — so it is safe to store as a reference. Internal database identifiers are never exposed.

Asset slugs are unique per (workspace, asset type) rather than per workspace, which is why assets are nested under their type in the URL.

Pagination

List endpoints are cursor-paginated. Pass limit to size a page, and pass the nextCursor from a response as cursor to fetch the following one. nextCursor is null on the last page.

Cursors are opaque: treat them as strings and do not construct them. Cursor paging stays stable while data changes underneath you — resources created mid-walk will not cause a skipped or duplicated result, which offset paging cannot promise.

Your first calls

This walkthrough goes from an empty workspace to a published view. Every request is complete — substitute your region, key and slugs. AU is used throughout; use the base URL for your region.

1. Find your workspace

Workspaces are addressed by slug, and this is where you get them:

curl https://api.au.aplas.com/api/v3/workspaces \
  -H "Authorization: Bearer $APLAS_KEY"

{ "data": [ { "id": "enterprise", "name": "Enterprise" } ], "nextCursor": null }

Use id — enterprise here — everywhere a workspace is named below.

2. Create an asset type

An asset type is the shape of a thing you catalogue. id is the slug you will address it by, and fieldSpecs declares the fields its assets carry:

curl -X POST https://api.au.aplas.com/api/v3/workspaces/enterprise/asset-types \
  -H "Authorization: Bearer $APLAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "application",
    "nameSingular": "Application",
    "namePlural": "Applications",
    "fieldSpecs": [
      { "id": "vendor", "name": "Vendor", "type": "text" },
      { "id": "lifecycle", "name": "Lifecycle", "type": "choice",
        "options": [
          { "value": "standard", "label": "Standard" },
          { "value": "retired",  "label": "Retired" }
        ] }
    ]
  }'

A 409 here means the slug is already used in this workspace.

3. Create assets

One at a time:

curl -X POST https://api.au.aplas.com/api/v3/workspaces/enterprise/asset-types/application/assets \
  -H "Authorization: Bearer $APLAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CRM System", "fields": { "vendor": "Acme", "lifecycle": "standard" } }'

The response carries the asset's id — a slug derived from name unless you supplied one. Asset slugs are unique per type, not per workspace, which is why the type appears in the path.

For a batch, POST a JSON array of the same objects to /assets/bulk — the array is the body, not an object wrapping one. It returns a per-item result, so one bad row does not cost you the other 999; the limit is 1000 per call. There is also /assets/bulk-op for applying a single operation across many assets.

A field's declared type decides what its values must be. choice fields are the ones worth care: values are matched against each option's value, not its label, so "lifecycle": "standard" is accepted above and "Standard" is not. The full set of field types is in the Asset Types reference.

4. Relate them

Relationship types are read-only: they arrive with the standard template, or are minted when an asset type declares a relation field. List the ones available before you write:

curl https://api.au.aplas.com/api/v3/workspaces/enterprise/relationship-types \
  -H "Authorization: Bearer $APLAS_KEY"

Then set an asset's targets for one of them. Targets name both the type slug and the asset slug, because an asset slug alone is ambiguous:

curl -X PUT "https://api.au.aplas.com/api/v3/workspaces/enterprise/asset-types/application/assets/crm-system/relations/depends-on" \
  -H "Authorization: Bearer $APLAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targets": [ { "type": "application", "id": "identity-provider" } ] }'

PUT replaces this asset's targets for that relationship type. Use POST on the same path to add without removing what is already there.

5. Create a view, then publish it

A view is a saved configuration — a map, table, matrix, graph or search — over the workspace:

curl -X POST https://api.au.aplas.com/api/v3/workspaces/enterprise/views \
  -H "Authorization: Bearer $APLAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Application landscape", "viewType": "map" }'

Publishing is organization-level, because a publication's slug is unique across your organization rather than within one workspace:

curl -X POST https://api.au.aplas.com/api/v3/publications \
  -H "Authorization: Bearer $APLAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "landscape",
    "name": "Application landscape",
    "view": { "workspace": "enterprise", "id": "application-landscape" },
    "enabled": true
  }'

Only views in the default workspace may publish.

OpenAPI Specification

The full v3 API is described by an OpenAPI 3.0 document, published at:

https://docs.aplas.com/openapi-v3.yaml

Use this URL to:

• Import into Postman, Insomnia, or Stoplight
• Generate typed clients with openapi-generator or openapi-typescript
• Feed to LLM tooling for code generation

Download openapi-v3.yaml

The v2 specification stays published at /openapi.yaml

MCP for AI assistants

Aplas also exposes a Model Context Protocol server at the same regional hosts, under /mcp/v1:

https://api.au.aplas.com/mcp/v1
https://api.eu.aplas.com/mcp/v1
https://api.us.aplas.com/mcp/v1

This lets Claude, Cursor, GitHub Copilot and other AI assistants read and write your data using the same API key as a Bearer token, and the same ReadOnly / ReadWrite roles apply. Unlike the assistant inside Aplas, an MCP write takes effect immediately — there is no confirmation step.

See Connecting AI assistants for what it can do, and MCP server setup for client-specific configuration.

What's next

Browse the sidebar for operations grouped by resource — start with Workspaces, then Asset Types and Assets.