v1

Hermiis REST API

Integrate Hermiis into your CI/CD pipelines, internal tools, and automations. Read and write workspaces, boards, tasks, and features using standard JSON over HTTPS.

Secure

HTTPS-only, Bearer token auth, SHA-256 hashed token storage.

Fast

JSON responses. Up to 300 req/5 min per token.

OpenAPI

Machine-readable spec at /openapi.json.

Base URL

text
https://hermiis.com/api/v1

Authentication

The API uses Personal Access Tokens (PAT). Generate one in your account: Settings → API Tokens.

Include the token in every request as a Bearer token in the Authorization header:

bash
Authorization: Bearer hrm_at_xxxxxxxxxxxxxxxxxxxx
curl
curl -X GET https://hermiis.com/api/v1/workspaces \
  -H "Authorization: Bearer hrm_at_xxxxxxxxxxxxxxxxxxxx"
⚠ Keep tokens secret. Tokens are hashed (SHA-256) before storage — Hermiis cannot recover a lost token. Rotate immediately if compromised.

Errors

All errors return a JSON body with an error key (or errors for validation failures).

Status Meaning Body
200 OK Request succeeded {"resource": {…}}
201 Created Resource created {"resource": {…}}
401 Unauthorized Missing or invalid token {"error": "Unauthorized"}
403 Forbidden Not a workspace member {"error": "Forbidden"}
404 Not Found Resource not found {"error": "Not found"}
422 Unprocessable Entity Validation failed {"errors": {"title": ["can't be blank"]}}
429 Too Many Requests Rate limit exceeded {"error": "Too many requests"}

Rate Limiting

Each API token is limited to 300 requests per 5-minute window. When the limit is exceeded the server returns 429 Too Many Requests.

Workspaces

GET /workspaces

List workspaces

Returns all workspaces the authenticated user belongs to.

Response Fields

Field Type Description
id string (ULID) Unique identifier
name string Display name
slug string URL-safe slug used in all API paths
inserted_at ISO 8601 Creation timestamp

Example Request

curl https://hermiis.com/api/v1/workspaces \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "workspaces": [
    {
      "id": "01HRXYZ123ABCDEFGH456789",
      "name": "Acme Engineering",
      "slug": "acme",
      "inserted_at": "2025-01-15T10:23:00Z"
    }
  ]
}

Boards

GET /workspaces/:workspace_slug/boards

List boards

Returns all boards in a workspace. Must be a workspace member.

Path Parameters

Name Type Description
workspace_slug * string Workspace URL slug (e.g. acme)

Response Fields

Field Type Description
id string (ULID) Unique identifier
name string Board display name
slug string URL-safe board slug
inserted_at ISO 8601 Creation timestamp

Example Request

curl https://hermiis.com/api/v1/workspaces/acme/boards \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "boards": [
    {"id": "01HRYYYY456XYZABCDEF1234", "name": "Main Track", "slug": "mt", "inserted_at": "2025-01-20T08:00:00Z"},
    {"id": "01HRBBBB789", "name": "Design System", "slug": "ds", "inserted_at": "2025-01-22T12:30:00Z"}
  ]
}

Tasks

GET /workspaces/:workspace_slug/boards/:board_slug/tasks

List tasks

Returns all tasks on a board.

Path Parameters

Name Type Description
workspace_slug * string Workspace slug
board_slug * string Board slug

Response Fields

Field Type Description
id string (ULID) Task ULID — use this in PATCH URLs
title string Task title
description string | null Markdown body
priority urgent|high|medium|low|null Priority level
estimated_hours number | null Estimated hours of effort
inserted_at ISO 8601 Creation timestamp
updated_at ISO 8601 Last updated timestamp

Example Request

curl https://hermiis.com/api/v1/workspaces/acme/boards/mt/tasks \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "tasks": [
    {
      "id": "01HRZZZZ789ABCDEFGH12345",
      "title": "Implement OAuth2 login",
      "description": "Add Google and GitHub SSO.",
      "priority": "high",
      "estimated_hours": 8,
      "inserted_at": "2025-02-01T09:30:00Z",
      "updated_at": "2025-02-03T14:15:00Z"
    }
  ]
}
POST /workspaces/:workspace_slug/boards/:board_slug/tasks

Create a task

Creates a new task. Placed in the first status column of the board.

Path Parameters

Name Type Description
workspace_slug * string Workspace slug
board_slug * string Board slug

Request Body (JSON)

Field Type Description
title * string Task title
description_markdown string Markdown body (optional)
priority urgent|high|medium|low Priority (optional)
estimated_hours number Estimated hours (optional)

Example Request

curl -X POST https://hermiis.com/api/v1/workspaces/acme/boards/mt/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix null pointer", "priority": "urgent", "estimated_hours": 2}'

Example Response

{
  "task": {
    "id": "01HRNEWW111ABCDEFGH99999",
    "title": "Fix null pointer",
    "description": null,
    "priority": "urgent",
    "estimated_hours": 2,
    "inserted_at": "2025-04-28T16:00:00Z",
    "updated_at": "2025-04-28T16:00:00Z"
  }
}
PATCH /workspaces/:workspace_slug/boards/:board_slug/tasks/:task_id

Update a task

Partial update — only fields you provide are changed. Omit fields you don't want to modify.

Path Parameters

Name Type Description
workspace_slug * string Workspace slug
board_slug * string Board slug
task_id * string (ULID) Task ULID from the id field

Request Body (JSON)

Field Type Description
title string New title (optional)
description_markdown string New Markdown body (optional)
priority urgent|high|medium|low|null Priority level (optional)
estimated_hours number|null Estimated hours (optional)

Example Request

curl -X PATCH \
  https://hermiis.com/api/v1/workspaces/acme/boards/mt/tasks/01HRZZZZ789ABCDEFGH12345 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority": "low", "estimated_hours": 4}'

Example Response

{
  "task": {
    "id": "01HRZZZZ789ABCDEFGH12345",
    "title": "Implement OAuth2 login",
    "description": "Add Google and GitHub SSO.",
    "priority": "low",
    "estimated_hours": 4,
    "inserted_at": "2025-02-01T09:30:00Z",
    "updated_at": "2025-04-28T16:05:00Z"
  }
}

Features

GET /workspaces/:workspace_slug/boards/:board_slug/features

List features

Returns all features (epics) on a board. Features group related tasks.

Path Parameters

Name Type Description
workspace_slug * string Workspace slug
board_slug * string Board slug

Response Fields

Field Type Description
id string (ULID) Feature ULID
title string Feature title
status draft|in_progress|done|archived Lifecycle status
inserted_at ISO 8601 Creation timestamp

Example Request

curl https://hermiis.com/api/v1/workspaces/acme/boards/mt/features \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "features": [
    {
      "id": "01HRAAAA000ABCDEFGH56789",
      "title": "Auth & Identity",
      "status": "in_progress",
      "inserted_at": "2025-01-22T11:00:00Z"
    }
  ]
}

Code Examples

# List workspaces
curl https://hermiis.com/api/v1/workspaces \
  -H "Authorization: Bearer $TOKEN"

# Create a task
curl -X POST https://hermiis.com/api/v1/workspaces/acme/boards/mt/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy to production", "priority": "high"}'