REST API

Everything the dashboard does goes through the Lahijan REST API, so you can script any of it. This page covers the rules shared by every endpoint. The complete, typed contract is the OpenAPI 3.1 spec in the repository at api/openapi.yaml.

Base URL and format

• All endpoints live under /api/v1/, on the same origin as the dashboard (for example https://lahijan.example.com/api/v1/). The exceptions are the health endpoints and the job queue UI.
• Request and response bodies are JSON unless an endpoint says otherwise (plugin upload is multipart, receipt downloads are PDF).
• JSON field names are camelCase (tenantId, createdAt).
• Timestamps are RFC 3339 strings in UTC. Ids are UUIDs, except job ids, which are integers.
• Send Accept-Language: fa to get error messages in Persian; English is the default.
• Every response carries an X-Request-ID header. Include it when you report a problem; it ties the request to logs and audit entries.

Authentication

There are two ways to authenticate. Unauthenticated requests are not rejected up front: they reach the endpoint as anonymous, and endpoints that need a user answer 401 unauthorized.

Session cookie (dashboard)

Signing in through POST /api/v1/auth/login sets a session cookie, lahijan_session by default, and a refresh cookie, lahijan_refresh. The browser sends them automatically. POST /api/v1/auth/refresh renews the session and POST /api/v1/auth/logout ends it. The cookie names come from auth.session.cookieName and auth.session.refreshCookieName.

Personal access token (scripts)

For scripts and tools, create a personal access token (see Access tokens) and send it as a bearer token:

GET /api/v1/compute/instances HTTP/1.1Host: lahijan.example.comAuthorization: Bearer lah_pat_...X-Tenant-Id: 6f1c2b7e-8a4d-4f7e-9c1a-2d3b4e5f6a7b

Send the token exactly as shown when it was created, including the lah_pat_ prefix. Revoked and expired tokens are treated as anonymous. Each use updates the token's last-used time and writes an audit entry. If a request carries both a valid session cookie and a token, the cookie wins.

Tenant scope

Most endpoints act inside one tenant. Tell Lahijan which one with a header:

They are tried in that order. The value is only a hint: every protected endpoint checks that you hold the needed permission in that tenant. A protected endpoint called without a usable tenant returns 400 with the code tenant_scope_required. Admin endpoints under /api/v1/admin/ need the header too.

Permissions

Each protected endpoint requires one permission, such as compute.instance.create or dns.record.delete. Without it you get 403 forbidden, and details.permission names the missing permission. The full list is in Permissions.

Errors

Every error uses the same envelope:

{	"error": {		"code": "forbidden",		"message": "You do not have permission to do that.",		"details": { "permission": "dns.zone.delete" }	}}

• code is a stable, machine-readable string. Switch on it.
• message is safe to show to users and is localized.
• details is optional and free-form; its shape depends on the error.

Error codes in use:

A few endpoints return other statuses with a standard code, such as 422 with bad_request when a marketplace hash does not match.

Pagination and filtering

List endpoints use offset pagination:

Responses wrap the items with the paging values:

{ "items": [ ... ], "total": 132, "limit": 50, "offset": 0 }

Some lists differ. Object version listings use S3-style markers (nextKeyMarker, nextVersionIdMarker, isTruncated). The admin jobs list does not apply offset (see Background jobs). Filters are plain query parameters specific to each endpoint, for example action, resourceType, fromTs and toTs on the audit log, or state, kind and queue on jobs.

Idempotency and rate limits

• Lahijan does not support an Idempotency-Key header. Retrying a POST can create a second resource; check before you retry.
• There is no general API rate limit. Only specific flows return 429, as listed above. Put a limit in your reverse proxy if you need one.

CORS

CORS is off by default because the dashboard is served from the same origin as the API. To call the API from a browser app on another origin, set the http.server.cors keys:

http:  server:    cors:      enabled: true      allowOrigins: ["https://app.example.com"]      allowMethods: ["GET", "POST", "PATCH", "DELETE"]      allowHeaders: ["Authorization", "Content-Type", "X-Tenant-Id"]      maxAge: 600

Request size

The server's body limit is http.server.bodylimit, 4 MiB by default. Larger requests get 413 payload_too_large. Endpoints can apply smaller limits of their own.

Health checks

The liveness and readiness probes do not check the database or the backends; they only show the process is serving HTTP.

OpenAPI spec and clients

api/openapi.yaml is the single source of truth. Code generated from it is committed to the repository:

Regenerate with make openapi-gen. sdk-go/ is a different thing: the SDK for writing plugins, not a REST client.

client, err := lahijanclient.NewClient("https://lahijan.example.com")if err != nil {	return err}resp, err := client.PingWithResponse(ctx)

Endpoint groups

Paths from the OpenAPI spec, grouped by area. Braces mark path parameters.

Paths in a row that do not start with / are relative to the first path in that row.