Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pixlcore/xyops/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

xyOps supports two authentication methods for API requests:
  1. API Keys - For server-to-server integrations and automation
  2. Session Tokens - For user-initiated requests from the web UI

​
API Keys

API Keys allow you to register external applications or services to use the REST API. These can be thought of as special user accounts specifically for applications. Each API key can be granted a specific set of privileges.

​
Creating API Keys

To create an API Key:
  1. Login to the xyOps UI as an administrator
  2. Navigate to the API Keys tab
  3. Click Add API Key…
  4. Fill out the form with:
    • Title (descriptive name)
    • Privileges (select permissions)
    • Optional expiration date
    • Optional rate limit
  5. Click Create Key

​
API Key Format

API Keys are randomly generated alphanumeric strings, 24 characters in length by default. They are case sensitive. Example: 
muJm8T6QSzqQzuO6MvbOdtlB

​
Using API Keys

You must include a valid API Key with every API request. There are three ways to do this: 
curl -H "X-API-Key: muJm8T6QSzqQzuO6MvbOdtlB" \
  https://sample.west.xyops.io/api/app/get_events/v1

​
2. Query String Parameter

curl https://sample.west.xyops.io/api/app/get_events/v1?api_key=muJm8T6QSzqQzuO6MvbOdtlB

​
3. JSON Property

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"api_key": "muJm8T6QSzqQzuO6MvbOdtlB", "query": "*"}' \
  https://sample.west.xyops.io/api/app/search_jobs/v1
Only one authentication method is required. Using the X-API-Key header is recommended for security.

​
Rate Limiting

API Keys support rate limiting on a per-second basis. When a key exceeds its rate limit, you’ll receive: 
{
  "code": "rate",
  "description": "API Key has exceeded rate limit (100/sec)"
}

​
Expiration

API Keys can be configured with an optional expiration date. Attempting to use an expired key returns: 
{
  "code": "api",
  "description": "API Key is expired"
}

​
Session Tokens

Session tokens are used for user-initiated requests, typically from the web UI. Sessions are created upon user login and expire after a period of inactivity.

​
Using Session Tokens

Include the session ID in one of these ways: 
curl -b "session_id=abc123def456" \
  https://sample.west.xyops.io/api/app/get_events/v1

​
2. HTTP Header

curl -H "X-Session-ID: abc123def456" \
  https://sample.west.xyops.io/api/app/get_events/v1

​
3. Query Parameter

curl https://sample.west.xyops.io/api/app/get_events/v1?session_id=abc123def456
Session tokens are automatically managed by the web UI. For programmatic access, use API Keys instead.

​
Privileges and Permissions

Both API Keys and user sessions are subject to privilege checks. Common privileges include:
PrivilegeDescription
adminFull administrative access
create_eventsCreate new events
edit_eventsModify existing events
delete_eventsDelete events
run_jobsLaunch jobs manually
abort_jobsAbort running jobs
create_monitorsCreate monitoring definitions
create_alertsCreate alert definitions
create_ticketsCreate support tickets

​
Privilege Errors

When you lack required privileges: 
{
  "code": "access",
  "description": "You do not have the 'Run Jobs' privilege required to perform this action."
}

​
Category and Group Access

In addition to privileges, users and API Keys may be restricted to specific:
  • Categories - Event categories
  • Server Groups - Collections of servers
Attempting to access restricted resources returns: 
{
  "code": "access",
  "description": "You do not have the required account privileges to access category ID production."
}

​
Complete Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: muJm8T6QSzqQzuO6MvbOdtlB" \
  -d '{"id": "event100"}' \
  https://sample.west.xyops.io/api/app/run_event/v1

Build docs developers (and LLMs) love

Get started for freeTalk to us