Skip to content

Version: Arctyk ITSM v0.6.0+ Last Updated: January 2026

REST API Documentation

Arctyk ITSM provides a comprehensive REST API for programmatic access to tickets, comments, projects, and assets.

Overview

Base URL

https://arctyk.example.com/api/

Authentication

All API requests require authentication using a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://arctyk.example.com/api/tickets/

Response Format

All responses are JSON:

{
  "id": 1,
  "title": "Example Ticket",
  "description": "Ticket description",
  "status": "open",
  "priority": "high",
  "created_at": "2026-01-03T10:00:00Z"
}

Error Handling

HTTP Status Codes

Code Meaning
200 Success
201 Created
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Server Error

Error Response

{
  "error": "Validation failed",
  "details": {
    "title": ["This field is required"]
  }
}

Tickets API

List Tickets

GET /api/tickets/

List all tickets (paginated).

Query Parameters

Parameter Type Description
q string Search by title, description, or ticket number
status string Filter by status (e.g., open, closed)
priority string Filter by priority (e.g., high, medium)
assigned string Filter by assignee (me, any, or user ID)
page integer Page number (default: 1)
limit integer Results per page (default: 20)

Example

curl -H "Authorization: Bearer TOKEN" \
  "https://arctyk.example.com/api/tickets/?status=open&priority=high"

Response

{
  "count": 150,
  "next": "/api/tickets/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "ticket_number": "TKT-001",
      "title": "Unable to login",
      "description": "Users cannot access the system",
      "status": "open",
      "priority": "high",
      "requester": "user@example.com",
      "assigned_to": "agent@example.com",
      "created_at": "2026-01-03T10:00:00Z",
      "updated_at": "2026-01-03T15:00:00Z"
    }
  ]
}

Get Ticket

GET /api/tickets/<id>/

Retrieve a single ticket by ID.

Response

{
  "id": 1,
  "ticket_number": "TKT-001",
  "title": "Unable to login",
  "description": "Users cannot access the system",
  "status": "open",
  "status_category": "todo",
  "priority": "high",
  "requester": {
    "id": 1,
    "username": "user@example.com",
    "full_name": "John Doe"
  },
  "assigned_to": {
    "id": 2,
    "username": "agent@example.com",
    "full_name": "Jane Smith"
  },
  "project": {
    "id": 1,
    "name": "Platform"
  },
  "created_at": "2026-01-03T10:00:00Z",
  "updated_at": "2026-01-03T15:00:00Z",
  "due_date": "2026-01-10",
  "comments_count": 5,
  "attachments": []
}

Create Ticket

POST /api/tickets/

Create a new ticket.

Request Body

{
  "title": "New support request",
  "description": "Detailed description of the issue",
  "priority": "medium",
  "project": 1,
  "assigned_to": 2
}

Response (201 Created)

{
  "id": 123,
  "ticket_number": "TKT-123",
  "title": "New support request",
  "status": "new",
  "priority": "medium",
  "created_at": "2026-01-03T10:00:00Z"
}

Update Ticket

PATCH /api/tickets/<id>/

Update an existing ticket.

Request Body

{
  "status": "in_progress",
  "assigned_to": 2,
  "priority": "high"
}

Response (200 OK)

{
  "id": 1,
  "ticket_number": "TKT-001",
  "title": "Unable to login",
  "status": "in_progress",
  "priority": "high",
  "updated_at": "2026-01-03T15:30:00Z"
}

Delete Ticket

DELETE /api/tickets/<id>/

Delete a ticket (soft delete - archives it).

Response (204 No Content)

Empty response.

Comments API (v0.6.0+)

List Comments

GET /api/tickets/<ticket_id>/comments/

List all comments for a ticket.

Response

[
  {
    "id": 1,
    "ticket": 123,
    "author": {
      "id": 1,
      "username": "user@example.com",
      "full_name": "John Doe"
    },
    "content": "This is a public comment",
    "comment_type": "public",
    "created_at": "2026-01-03T10:00:00Z",
    "updated_at": "2026-01-03T10:05:00Z",
    "edit_count": 0
  }
]

Create Comment

POST /api/tickets/<ticket_id>/comments/

Add a comment to a ticket.

Request Body

{
  "content": "Investigating the issue now",
  "comment_type": "public"
}

Comment Types:

  • public - Visible to requester and team
  • internal - Visible to team only

Response (201 Created)

{
  "id": 5,
  "ticket": 123,
  "author": "agent@example.com",
  "content": "Investigating the issue now",
  "comment_type": "public",
  "created_at": "2026-01-03T11:00:00Z"
}

Update Comment

PATCH /api/tickets/<ticket_id>/comments/<comment_id>/

Edit a comment (only author or admin can edit).

Request Body

{
  "content": "Updated comment text"
}

Response (200 OK)

{
  "id": 5,
  "content": "Updated comment text",
  "updated_at": "2026-01-03T11:05:00Z",
  "edit_count": 1,
  "edit_history": [
    {
      "edited_at": "2026-01-03T11:05:00Z",
      "previous_content": "Investigating the issue now"
    }
  ]
}

Delete Comment

DELETE /api/tickets/<ticket_id>/comments/<comment_id>/

Delete a comment (only author or admin can delete).

Response (204 No Content)

Empty response.

Projects API

List Projects

GET /api/projects/

List all projects.

Response

[
  {
    "id": 1,
    "name": "Platform",
    "description": "Main platform project",
    "ticket_count": 45,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Get Project

GET /api/projects/<id>/

Retrieve a single project.

Create Project

POST /api/projects/

Create a new project.

Update Project

PATCH /api/projects/<id>/

Update a project.

Delete Project

DELETE /api/projects/<id>/

Delete a project.

Assets API

List Assets

GET /api/assets/

List all assets (inventory items).

Query Parameters

Parameter Type Description
type string Filter by asset type
status string Filter by status
search string Search by name or description

Response

[
  {
    "id": 1,
    "name": "Server-001",
    "type": "server",
    "status": "active",
    "location": "Data Center A",
    "owner": "admin@example.com"
  }
]

Get Asset

GET /api/assets/<id>/

Retrieve a single asset.

Create Asset

POST /api/assets/

Create a new asset.

Update Asset

PATCH /api/assets/<id>/

Update an asset.

Delete Asset

DELETE /api/assets/<id>/

Delete an asset.

Examples

Python

import requests

BASE_URL = 'https://arctyk.example.com/api'
TOKEN = 'your-api-token'

headers = {
    'Authorization': f'Bearer {TOKEN}',
    'Content-Type': 'application/json'
}

# Create a ticket
response = requests.post(
    f'{BASE_URL}/tickets/',
    headers=headers,
    json={
        'title': 'API Created Ticket',
        'description': 'Created via REST API',
        'priority': 'high'
    }
)
ticket = response.json()
print(f'Created ticket: {ticket["id"]}')

# Add a comment
response = requests.post(
    f'{BASE_URL}/tickets/{ticket["id"]}/comments/',
    headers=headers,
    json={
        'content': 'First comment via API',
        'comment_type': 'public'
    }
)

JavaScript

const BASE_URL = "https://arctyk.example.com/api";
const TOKEN = "your-api-token";

async function createTicket(title, description) {
  const response = await fetch(`${BASE_URL}/tickets/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title,
      description,
      priority: "medium",
    }),
  });

  return response.json();
}

async function addComment(ticketId, content) {
  const response = await fetch(`${BASE_URL}/tickets/${ticketId}/comments/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content,
      comment_type: "public",
    }),
  });

  return response.json();
}

cURL

# List tickets
curl -H "Authorization: Bearer TOKEN" \
  https://arctyk.example.com/api/tickets/

# Create ticket
curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New ticket","priority":"high"}' \
  https://arctyk.example.com/api/tickets/

# Add comment
curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Comment text","comment_type":"public"}' \
  https://arctyk.example.com/api/tickets/1/comments/

Pagination

List endpoints return paginated results:

{
  "count": 150,
  "next": "/api/tickets/?page=2",
  "previous": null,
  "results": [...]
}

Use the page parameter to navigate:

curl https://arctyk.example.com/api/tickets/?page=2

Rate Limiting

API calls are rate-limited to prevent abuse:

  • Authenticated: 1000 requests per hour
  • Unauthenticated: 100 requests per hour

Check response headers for rate limit info:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704285600