Skip to content

feat: add edge urls #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aisha331 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: add edge urls #15

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bdb57a0
add edge urls
aisha331 Mar 11, 2026
9c13743
rm api capabilities
aisha331 Mar 11, 2026
3ce0f13
cache non edge ds
aisha331 Mar 11, 2026
f97177d
try edge regions
aisha331 Mar 12, 2026
80e10d3
no regex
aisha331 Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 250 additions & 0 deletions skill/reference/api-capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,250 @@
# Axiom API Capabilities

Summary of all operations available via Axiom API.

**Base URL:** `https://api.axiom.co` (for management endpoints)
**Query & Ingest URL:** Auto-resolved per dataset via `scripts/resolve-url`

**Authentication:**
- `Authorization: Bearer $API_TOKEN` — use an advanced API token with minimal privileges

---

## Querying

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| Run APL query | `POST /v1/datasets/_apl?format=tabular` | Execute APL query with tabular output |
| Run APL query (legacy) | `POST /v1/datasets/_apl?format=legacy` | Execute APL query with legacy output |
| Run query (legacy) | `POST /v1/datasets/{dataset_name}/query` | Legacy query endpoint with filter/aggregation model |

**Query parameters:** `apl`, `startTime`, `endTime`, `cursor`, `includeCursor`, `queryOptions`, `variables`

---

## Datasets

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List datasets | `GET /v1/datasets` | List all datasets in the organization |
| Get dataset | `GET /v1/datasets/{dataset_id}` | Retrieve dataset metadata by ID |
| Create dataset | `POST /v1/datasets` | Create a new dataset |
| Update dataset | `PUT /v1/datasets/{dataset_id}` | Update dataset description, retention |
| Delete dataset | `DELETE /v1/datasets/{dataset_id}` | Permanently delete a dataset |
| Trim dataset | `POST /v1/datasets/{dataset_name}/trim` | Delete data older than specified duration |
| Vacuum dataset | `POST /v1/datasets/{dataset_id}/vacuum` | Reclaim storage space (async operation) |

---

## Ingestion

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| Ingest data (edge) | `POST /v1/ingest/{dataset_id}` | Ingest JSON/NDJSON/CSV via edge endpoint |
| Ingest data (API) | `POST /v1/datasets/{dataset_name}/ingest` | Ingest JSON/NDJSON/CSV via API endpoint |

**Headers:** `X-Axiom-CSV-Fields`, `X-Axiom-Event-Labels`
**Query params:** `timestamp-field`, `timestamp-format`, `csv-delimiter`
**Formats:** JSON, NDJSON, CSV

---

## Fields

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List fields | `GET /v1/datasets/{dataset_id}/fields` | List all fields in a dataset |
| Get field | `GET /v1/datasets/{dataset_id}/fields/{field_id}` | Get field metadata |
| Update field | `PUT /v1/datasets/{dataset_id}/fields/{field_id}` | Update field description, unit, hidden status |

---

## Map Fields

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List map fields | `GET /v1/datasets/{dataset_id}/mapfields` | List fields marked as maps |
| Create map field | `POST /v1/datasets/{dataset_id}/mapfields` | Mark a field as a map type |
| Update map fields | `PUT /v1/datasets/{dataset_id}/mapfields` | Replace entire list of map fields |
| Delete map field | `DELETE /v1/datasets/{dataset_id}/mapfields/{map_field_name}` | Remove map field designation |

---

## Virtual Fields

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List virtual fields | `GET /v1/vfields?dataset={dataset}` | List virtual fields for a dataset |
| Get virtual field | `GET /v1/vfields/{id}` | Get virtual field by ID |
| Create virtual field | `POST /v1/vfields` | Create computed field with APL expression |
| Update virtual field | `PUT /v1/vfields/{id}` | Update virtual field expression |
| Delete virtual field | `DELETE /v1/vfields/{id}` | Delete virtual field |

---

## Annotations

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List annotations | `GET /v1/annotations` | List all annotations (filter by datasets, start, end) |
| Get annotation | `GET /v1/annotations/{id}` | Get annotation by ID |
| Create annotation | `POST /v1/annotations` | Create annotation marking an event on charts |
| Update annotation | `PUT /v1/annotations/{id}` | Update annotation properties |
| Delete annotation | `DELETE /v1/annotations/{id}` | Delete annotation |

**Fields:** `datasets[]`, `type`, `time`, `endTime`, `title`, `description`, `url`

---

## Monitors (Alerts)

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List monitors | `GET /v1/monitors` | List all configured monitors |
| Get monitor | `GET /v1/monitors/{id}` | Get monitor configuration |
| Get monitor history | `GET /v1/monitors/{id}/history` | Get alert history for a monitor |
| Create monitor | `POST /v1/monitors` | Create new monitor (Threshold/MatchEvent/AnomalyDetection) |
| Update monitor | `PUT /v1/monitors/{id}` | Update monitor configuration |
| Delete monitor | `DELETE /v1/monitors/{id}` | Delete monitor |

**Monitor types:** `Threshold`, `MatchEvent`, `AnomalyDetection`
**Operators:** `Below`, `BelowOrEqual`, `Above`, `AboveOrEqual`, `AboveOrBelow`

---

## Notifiers

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List notifiers | `GET /v1/notifiers` | List all notification channels |
| Get notifier | `GET /v1/notifiers/{id}` | Get notifier configuration |
| Create notifier | `POST /v1/notifiers` | Create notification channel |
| Update notifier | `PUT /v1/notifiers/{id}` | Update notifier configuration |
| Delete notifier | `DELETE /v1/notifiers/{id}` | Delete notifier |

**Channel types:** Slack, Email, PagerDuty, OpsGenie, Discord, Microsoft Teams, Custom Webhooks

---

## Saved Queries

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List saved queries | `GET /v1/apl-starred-queries` | List saved/starred APL queries |
| Get saved query | `GET /v1/apl-starred-queries/{id}` | Get saved query by ID |
| Create saved query | `POST /v1/apl-starred-queries` | Save an APL query |
| Update saved query | `PUT /v1/apl-starred-queries/{id}` | Update saved query |
| Delete saved query | `DELETE /v1/apl-starred-queries/{id}` | Delete saved query |

**Query params:** `limit`, `offset`, `dataset`, `who` (`team`/`all`/user ID), `qs`

---

## Views

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List views | `GET /v1/views` | List all views |
| Get view | `GET /v1/views/{id}` | Get view by ID |
| Create view | `POST /v1/views` | Create a view (pre-filtered dataset) |
| Update view | `PUT /v1/views/{id}` | Update view configuration |
| Delete view | `DELETE /v1/views/{id}` | Delete view |

**Fields:** `name`, `aplQuery`, `datasets[]`, `description`

---

## API Tokens

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List tokens | `GET /v1/tokens` | List all API tokens |
| Get token | `GET /v1/tokens/{id}` | Get token metadata (not the token value) |
| Create token | `POST /v1/tokens` | Create new API token with capabilities |
| Regenerate token | `POST /v1/tokens/{id}/regenerate` | Regenerate token value |
| Delete token | `DELETE /v1/tokens/{id}` | Delete API token |

**Capabilities:** `datasetCapabilities`, `orgCapabilities`, `viewCapabilities`

---

## Users

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| Get current user | `GET /v1/user` | Get authenticated user info (PAT only) |
| Update current user | `PUT /v1/user` | Update own user profile (PAT only) |
| List users | `GET /v1/users` | List all users in organization |
| Get user | `GET /v1/users/{id}` | Get user by ID |
| Create user | `POST /v1/users` | Invite/create user in organization |
| Update user role | `PUT /v1/users/{id}/role` | Change user's role |
| Remove user | `DELETE /v1/users/{id}` | Remove user from organization |

---

## Organizations

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List orgs | `GET /v1/orgs` | List organizations user belongs to |
| Get org | `GET /v1/orgs/{id}` | Get organization details |
| Create org | `POST /v1/orgs` | Create new organization |
| Update org | `PUT /v1/orgs/{id}` | Update organization name/region |

---

## RBAC - Roles

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List roles | `GET /v1/rbac/roles` | List all roles with permissions |
| Get role | `GET /v1/rbac/roles/{id}` | Get role by ID |
| Create role | `POST /v1/rbac/roles` | Create custom role with capabilities |
| Update role | `PUT /v1/rbac/roles/{id}` | Update role permissions/members |
| Delete role | `DELETE /v1/rbac/roles/{id}` | Delete role |

**Capabilities:** `datasetCapabilities`, `orgCapabilities`, `viewCapabilities`

---

## RBAC - Groups

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| List groups | `GET /v1/rbac/groups` | List all groups |
| Get group | `GET /v1/rbac/groups/{id}` | Get group by ID |
| Create group | `POST /v1/rbac/groups` | Create user group |
| Update group | `PUT /v1/rbac/groups/{id}` | Update group members/roles |
| Delete group | `DELETE /v1/rbac/groups/{id}` | Delete group |

**Fields:** `name`, `description`, `members[]`, `roles[]`

---

## Rate Limits

| Header | Description |
|--------|-------------|
| `X-RateLimit-Scope` | `user` or `organization` |
| `X-RateLimit-Limit` | Max requests per minute |
| `X-RateLimit-Remaining` | Remaining requests in window |
| `X-RateLimit-Reset` | UTC epoch seconds when window resets |
| `X-QueryLimit-Limit` | Query cost limit (GB*ms) |
| `X-QueryLimit-Remaining` | Remaining query capacity |
| `X-QueryLimit-Reset` | UTC epoch seconds when query limit resets |

**Error:** `429 Too Many Requests` when rate limit exceeded

---

## API Reference

Full documentation: https://axiom.co/docs/restapi/introduction

### Common Response Codes
- `200` - Success
- `201` - Created
- `204` - No Content (success, no body)
- `403` - Forbidden (auth failure or insufficient permissions)
- `404` - Not Found
- `429` - Rate Limit Exceeded
Comment thread
aisha331 marked this conversation as resolved.
Outdated
9 changes: 4 additions & 5 deletions skill/reference/axiom.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
# Axiom API Capabilities

Summary of all operations available via Axiom API with a personal access token (PAT).
Summary of all operations available via Axiom API.

**Base URL:** `https://api.axiom.co` (for all endpoints except ingestion)
**Ingest URL:** Use edge deployment domain (e.g., `https://us-east-1.aws.edge.axiom.co`)
**Base URL:** `https://api.axiom.co` (for management endpoints)
**Query & Ingest URL:** Auto-resolved per dataset via `scripts/resolve-url`

**Authentication:**
- PAT: `Authorization: Bearer $PAT` + `x-axiom-org-id: $ORG_ID`
- API Token: `Authorization: Bearer $API_TOKEN`
- `Authorization: Bearer $API_TOKEN` — use an advanced API token with minimal privileges

---

Expand Down
28 changes: 26 additions & 2 deletions skill/scripts/axiom-api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,32 @@ fi
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
eval "$("$SCRIPT_DIR/config" axiom "$DEPLOYMENT")"

# Auto-resolve edge URL for query and ingest endpoints
Copy link
Copy Markdown
Contributor

@tsenart tsenart Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain what's going on here? Why do we need to auto-resolve anything? Why don't we use the configured axiom url directly?

Copy link
Copy Markdown
Author

@aisha331 aisha331 Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because core APIs for ingest and query will be deprecated as part of multiregion, we're moving to route those directly to the edge endpoint. This also correctly handles multi region ds, since queries go to the right regional edge

REQUEST_URL="$AXIOM_URL"
REQUEST_ENDPOINT="$ENDPOINT"
case "$ENDPOINT" in
/v1/datasets/_apl*|/v1/ingest/*)
DATASET=""
if [[ "$ENDPOINT" == /v1/ingest/* ]]; then
DATASET="${ENDPOINT#/v1/ingest/}"
DATASET="${DATASET%%[?/]*}"
elif [[ -n "$BODY" ]]; then
DATASET=$(echo "$BODY" | jq -r '.apl // empty' 2>/dev/null | grep -oE "^\['[^']+'\]|^\[\"[^\"]+\"\]|^\[[a-zA-Z0-9_-]+\]" | head -1 | tr -d "[]'\"" || true)
Comment thread
tsenart marked this conversation as resolved.
Outdated
fi
if [[ -n "$DATASET" ]]; then
RESOLVED=$("$SCRIPT_DIR/resolve-url" "$DEPLOYMENT" "$DATASET" 2>/dev/null || true)
if [[ -n "$RESOLVED" && "$RESOLVED" != "$AXIOM_URL" ]]; then
REQUEST_URL="$RESOLVED"
if [[ "$ENDPOINT" == /v1/datasets/_apl* ]]; then
REQUEST_ENDPOINT="/v1/query/_apl${ENDPOINT#/v1/datasets/_apl}"
fi
fi
fi
;;
esac

if [[ -n "$BODY" ]]; then
"$SCRIPT_DIR/curl-auth" axiom "$DEPLOYMENT" -X "$METHOD" -d "$BODY" "${AXIOM_URL}${ENDPOINT}"
"$SCRIPT_DIR/curl-auth" axiom "$DEPLOYMENT" -X "$METHOD" -d "$BODY" "${REQUEST_URL}${REQUEST_ENDPOINT}"
else
"$SCRIPT_DIR/curl-auth" axiom "$DEPLOYMENT" -X "$METHOD" "${AXIOM_URL}${ENDPOINT}"
"$SCRIPT_DIR/curl-auth" axiom "$DEPLOYMENT" -X "$METHOD" "${REQUEST_URL}${REQUEST_ENDPOINT}"
fi
2 changes: 1 addition & 1 deletion skill/scripts/axiom-link
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,10 @@ fi
# Derive web UI URL from configured API URL
# Replace "api." with "app." in the domain
# Examples:
# https://api.axiom.co → https://app.axiom.co
# https://api.staging.axiom.co → https://app.staging.axiom.co
# https://api.dev.axiom.co → https://app.dev.axiom.co
# https://cloud.axiom.co → https://app.axiom.co
# https://api.axiom.co → https://app.axiom.co
if [[ "$URL" == *"cloud.axiom.co"* ]]; then
BASE_URL="https://app.axiom.co"
elif [[ "$URL" == https://api.* ]]; then
Expand Down
14 changes: 13 additions & 1 deletion skill/scripts/axiom-query
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,18 @@ PAYLOAD=$(jq -cn \
# shellcheck disable=SC1090
eval "$("$SCRIPT_DIR/config" axiom "$DEPLOYMENT")"

# Auto-resolve edge URL
QUERY_URL="$AXIOM_URL"
QUERY_PATH="/v1/datasets/_apl?format=tabular"
DATASET=$(echo "$APL" | grep -oE "^\['[^']+'\]|^\[\"[^\"]+\"\]|^\[[a-zA-Z0-9_-]+\]" | head -1 | tr -d "[]'\"" || true)
Comment thread
aisha331 marked this conversation as resolved.
Outdated
if [[ -n "$DATASET" ]]; then
RESOLVED=$("$SCRIPT_DIR/resolve-url" "$DEPLOYMENT" "$DATASET" 2>/dev/null || true)
if [[ -n "$RESOLVED" && "$RESOLVED" != "$AXIOM_URL" ]]; then
QUERY_URL="$RESOLVED"
QUERY_PATH="/v1/query/_apl?format=tabular"
fi
fi

RESP_HEADERS=$(mktemp)
RESP_BODY=$(mktemp)
cleanup() {
Expand All @@ -150,7 +162,7 @@ trap cleanup EXIT

# Execute query and pipe to formatter
HTTP_CODE=$(curl -sS -o "$RESP_BODY" -D "$RESP_HEADERS" -w "%{http_code}" \
-X POST "$AXIOM_URL/v1/datasets/_apl?format=tabular" \
-X POST "$QUERY_URL$QUERY_PATH" \
-H "Authorization: Bearer $AXIOM_TOKEN" \
-H "X-Axiom-Org-Id: $AXIOM_ORG_ID" \
-H "Content-Type: application/json" \
Expand Down
Loading
Loading