ClientSt0r — REST API Reference & Overview

API Overview

Three ways to access the platform programmatically.

The REST API covers all standard operations. The GraphQL endpoint is available for complex cross-entity queries. An interactive Swagger UI is included in every installation for exploration and testing.

REST API

Standard JSON over HTTPS

Standard HTTP verbs: GET, POST, PUT, PATCH, DELETE. Paginated list endpoints with consistent filtering via query parameters. All major platform functions covered — organisations, assets, vault, tickets, contracts, invoices, procurement, network, and more.

GraphQL

Flexible cross-entity queries

A single GraphQL endpoint for fetching nested related data in one request. Useful for reporting and dashboard integrations where REST would require multiple sequential calls — for example, fetching an org with all its assets and open tickets in a single query.

Interactive Explorer

Swagger UI — built in

Swagger UI is built into the application and available at /api/docs/ after installation. Test endpoints directly from the browser using your authenticated session. No separate tooling required.

Authentication

Three authentication methods.

JWT tokens are recommended for user sessions and scripted access. API keys are recommended for long-running integrations. Session authentication is used automatically by the built-in Swagger UI.

JWT Token

Recommended for scripted access

Obtain token: POST to /api/token/ with username and password
Response contains an access token and a refresh token
Include in requests: Authorization: Bearer <access_token>
Access tokens expire (configurable); use refresh token to obtain a new access token
Refresh: POST to /api/token/refresh/ with the refresh token

API Keys

Recommended for long-running integrations

Generated from the admin panel — per-user or per-integration
Include in requests: Authorization: Api-Key <key>
Keys can be scoped to specific resources and operations
Keys can be revoked independently without affecting other credentials
All API key activity is logged in the audit trail with key ID and endpoint

Session Authentication

Swagger UI and browser use

Standard Django session cookie, set on login
Used automatically by the built-in Swagger UI explorer
Works in the browser without additional headers
Not recommended for programmatic or automated access
Sessions expire based on the configured session lifetime

Token request

POST /api/token/ HTTP/1.1
Host: your-clientst0r.example.com
Content-Type: application/json

{
  "username": "apiuser",
  "password": "yourpassword"
}

Token response

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

API Endpoint Groups

Available endpoint groups.

All endpoints are under the /api/ prefix. The interactive Swagger UI at /api/docs/ documents every endpoint, request schema, and response format.

Group	Base Path	Covers
Organisations	/api/orgs/	Client organisations, contacts, org-level settings
Assets	/api/assets/	Hardware assets, asset types, serial numbers, linked orgs
Vault	/api/vault/	Credential records (read requires explicit vault permission), categories
Documentation	/api/docs/	KB articles, article versions, categories
Tickets	/api/tickets/	Ticket records, SLA data, time entries, ticket notes
Contracts	/api/contracts/	Contract records, billing types, renewal data
Invoices	/api/invoices/	Invoice records, line items, PDF generation
Procurement	/api/procurement/	Purchase orders, vendors, receiving records
Network	/api/network/	IPAM subnets, IP assignments, VLAN records
Users	/api/users/	User accounts, role assignments (admin only)
Audit	/api/audit/	Audit log entries (read only)
Integrations	/api/integrations/	Integration configurations (admin only)

Common Usage Examples

Representative API calls.

All requests require an Authorization header with a valid JWT token or API key. Replace your-clientst0r.example.com with your deployment hostname.

List all organisations

GET /api/orgs/?page=1&page_size=25 HTTP/1.1
Host: your-clientst0r.example.com
Authorization: Bearer <token>

Create a new ticket

POST /api/tickets/ HTTP/1.1
Host: your-clientst0r.example.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "org": 42,
  "subject": "Exchange server unreachable",
  "priority": "high",
  "assignee": 7,
  "description": "Client reports Exchange is not accepting connections."
}

List assets for an organisation

GET /api/assets/?org=42&type=server&page=1 HTTP/1.1
Host: your-clientst0r.example.com
Authorization: Bearer <token>

Retrieve a vault entry (requires vault permission)

GET /api/vault/123/ HTTP/1.1
Host: your-clientst0r.example.com
Authorization: Bearer <token>

Create a purchase order

POST /api/procurement/orders/ HTTP/1.1
Host: your-clientst0r.example.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "vendor": 5,
  "org": 42,
  "items": [
    {
      "description": "32GB DDR5 RAM",
      "quantity": 4,
      "unit_price": "89.00"
    }
  ]
}

Pagination & Filtering

Standard query parameters across all list endpoints.

All list endpoints return paginated results with a consistent response structure. Filtering, search, and date-range parameters are supported on most resource types.

All list endpoints return paginated results — no unbounded response sets
Default page size is 25; maximum is 100
Pagination query params: ?page=N&page_size=N
Response envelope includes count, next, previous, and results
Filter by organisation: ?org=<id> — available on all org-scoped resource types
Filter by status: ?status=open (tickets), ?status=active (assets, contracts)
Filter by date range: ?created_after=2024-01-01&created_before=2024-12-31
Full-text search: ?search=<term> on most list endpoints

Paginated response structure

{
  "count": 847,
  "next": "https://your-clientst0r.example.com/api/tickets/?page=2",
  "previous": null,
  "results": [
    { ... },
    { ... }
  ]
}

Rate Limiting & Security

API security posture.

API access is subject to the same security controls as interactive sessions, plus additional safeguards for programmatic access patterns.

API requests are subject to rate limiting — configurable per-user and globally in platform settings
All API requests are written to the audit log with user or key identity, endpoint, HTTP method, source IP, and timestamp
Vault endpoints have additional permission checks beyond standard RBAC — vault access must be explicitly granted
API keys can be revoked immediately from the admin panel with no service restart required
JWT tokens can be invalidated by revoking the session or rotating the SECRET_KEY (all tokens for all users are invalidated)
HTTPS is required — plaintext HTTP requests to API endpoints are rejected at the Nginx layer
Scope violations on API keys — accessing an endpoint outside the key's scope — are logged and return a 403 response

GraphQL

Flexible querying across related entities.

The GraphQL endpoint is suited to reporting integrations, dashboard data aggregation, and any use case where fetching nested related data in a single request reduces round trips.

Available at /api/graphql/

Same authentication as REST — JWT Bearer token or API key in the Authorization header

Schema introspection is available for tooling and documentation generation

Use for: fetching nested org → assets → tickets in a single query without multiple REST calls

Use for: building reporting integrations that aggregate data across resource types

Use for: dashboard data where multiple related entities are displayed together

Built-in GraphiQL explorer is available at the same URL when accessed in a browser with an authenticated session

Example GraphQL query

{
  organisation(id: 42) {
    name
    assets {
      hostname
      type
      serialNumber
    }
    openTickets {
      id
      subject
      priority
      assignee {
        name
      }
    }
  }
}