Docs/Quickstart

Quickstart

Go from zero to a working integration in under five minutes. This guide walks you through creating a robot token, defining an instrument type, and creating your first instrument — all from the command line.

Prerequisites

Before you start, you need two things:

A Ptolemy workspace

A robot token

In Workspace Settings → API Tokens, create a robot user with the Memberrole. Copy the token — it’s only shown once.

Robot tokens use the prefix ptk_live_ and authenticate on every request via the Authorization: Bearerheader. Unlike human users, robot users don’t use a login/refresh flow — the token is all you need.

Step 1 — Set up your environment

Save your base URL, workspace ID, and token as variables so you can reuse them throughout this guide.

# Replace these with your actual values
export PTOLEMY_URL="https://api.ptolemy.cloud/v1"
export PTOLEMY_WS="your-workspace-id"
export PTOLEMY_TOKEN="ptk_live_abc123..."

# Quick test — list instruments (should return empty data array)
curl "$PTOLEMY_URL/workspaces/$PTOLEMY_WS/instruments" \
  -H "Authorization: Bearer $PTOLEMY_TOKEN"

If everything’s wired up, you’ll get back an empty response:

Response — 200 OK

{ "data": [], "meta": { "next_cursor": null, "has_more": false } }

Step 2 — Create an instrument type

Instrument types define the schema for a class of instruments. Let’s create an “Equity” type with custom fields for exchange, ISIN, currency, and sector.

Note that type_id accepts either a UUID or the type’s identifier string. Field values come back in extra_fields_snapshot on the response.

Step 3 — Create an instrument

Now create an instrument that belongs to the Equity type. Custom field values go in the field_values object. The currency field has a default so we can omit it.

curl "$PTOLEMY_URL/workspaces/$PTOLEMY_WS/instruments" \
  -X POST \
  -H "Authorization: Bearer $PTOLEMY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BHP Group Ltd.",
    "identifier": "bhp.ax",
    "type_id": "equity",
    "field_values": {
      "exchange": "ASX",
      "isin": "AU000000BHP4",
      "sector": "Materials"
    }
  }'

Step 4 — Query with the filter API

For simple lookups, use query parameters on GET /instruments. For complex queries, use the POST-based filter API with nested conditions.

Example — POST /instruments/filter

{
  "type_id": "equity",
  "filter": {
    "and": [
      { "field": "field.exchange", "op": "eq", "value": "ASX" },
      { "field": "name", "op": "contains", "value": "BHP" }
    ]
  },
  "sort": "-updated_at",
  "limit": 10
}

Next steps

You’ve created a schema, added an instrument, and queried it back. Here’s where to go from here:

Instruments API reference →

Full endpoint documentation for types, fields, instruments, tags, and tag assignments.