Developer Reference

API Reference & Workspace-Aware Flows

Blitera exposes scoped API-key automation for links, files, collections, and access audits, plus session-only governance for key management and dedicated API key activity.

AI agents: start here

1 AI Agents: Use the manifest, read the guide, run the scripts.

The API manifest is the authoritative endpoint catalog. Do not infer endpoints from page HTML. Start with the ready-to-run link inventory scripts instead of inventing ad hoc curl calls.

Agent Discovery Canonical discovery JSON API Manifest Machine-readable endpoint contract Agent Guide Scopes, workspace rules, safe workflows PowerShell Start List links with env-based auth

2 Authentication

Blitera exposes two complementary authentication surfaces. Use scoped API keys for server-to-server automation across links, files, collections, and public access audit exports. Use session authentication for owner governance such as API key management and dedicated API key activity review.

API Key Header Example

X-API-Key: bl_your_api_key_here

Scope model

API keys are granted explicit MVP scopes: links:read/write/delete, files:read/write/delete, collections:read/write/delete, and audit:read. A missing scope is a hard authorization boundary, not a recoverable client-side condition.

Workspace allowlist

Personal scope is available by default. Workspace access is opt-in: when an API request includes workspace_id, the key must include both the required business scope and that workspace ID in its allowlist.

Agent-ready references

For automation agents, download the published Agent Guide, API Manifest, Agent Skill, and scripts from the Agent Pack before calling the API. Generate keys in your dashboard: Account Security → API Keys .

Security Guardrails

API keys are confidential. Never expose them in client-side code. API requests must never send a forged account_id; Blitera derives identity from the authenticated principal. Dedicated API key activity endpoints are session-only, so a key cannot audit or hide its own behavior. Blitera stores keys using SHA-256 hashing; we cannot recover them if lost.

3 Complete Agent Pack

Endpoints Reference

GET /api/links API Key

Lists links available to the API key. Requires `links:read`. Personal scope is available by default; `workspace_id` is accepted only when the workspace is explicitly allowlisted on the key.

Query Parameters

Param	Type	Default	Description
`page`	int	1	Current page number
`limit`	int	20	Max 100 items per page
`status`	string	-	Filter by: `active`, `expired`, `paused`
`encryption_mode`	string	-	Filter by: `PLAIN`, `SIMPLE`, `ADVANCED`
`target_type`	string	-	Filter by: `url`, `file`
`sort_by`	string	created_at	Sort by: `created_at`, `click_count`, `title`
`order`	string	desc	Sort order: `asc`, `desc`
`search`	string	-	Filter by share code, title or destination
`workspace_id`	string	-	Optional workspace scope. The API key must include this workspace in its allowlist.

Request Snippet

Sample JSON response

{
    "links": [
    {
        "share_code": "PRESSKIT",
        "title": "Q1 Press Release",
        "target_type": "file",
        "context_type": "workspace",
        "workspace_id": "ws_333c92d68a7545aa9060",
        "created_at": "2026-03-10T14:23:00Z",
        "status": "active"
    },
    {
        "share_code": "LATER",
        "title": "Social Post",
        "target_type": "url",
        "context_type": "personal",
        "workspace_id": null,
        "created_at": "2026-03-11T09:00:00Z",
        "status": "active"
    }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 1,
        "total_items": 2,
        "page_size": 20,
        "has_next": false,
        "has_prev": false
    }
}

GET /api/links/{share_code} API Key

Retrieves one link visible to the API key. Requires `links:read`; workspace links remain protected by the key workspace allowlist.

Request Snippet

Sample JSON response

{
    "share_code": "PRESSKIT",
    "title": "Q1 Press Release",
    "target_destination": "https://storage.blitera.com/files/press-q1.pdf",
    "target_type": "file",
    "context_type": "workspace",
    "workspace_id": "ws_333c92d68a7545aa9060",
    "created_at": "2026-03-10T14:23:00Z",
    "expires_at": "2026-06-10T00:00:00Z",
    "encryption_mode": "ADVANCED",
    "status": "active"
}

GET /api/files API Key

Lists files visible to the API key. Requires `files:read`. Workspace files require both the scope and an explicit workspace allowlist match.

Query Parameters

Param	Type	Default	Description
`workspace_id`	string	-	Optional workspace scope. The API key must include this workspace in its allowlist.

Request Snippet

Sample JSON response

[
    {
        "file_id": "834be095-cf87-4a30-a990-cd9f2f9a0457",
        "file_name": "press-q1.pdf",
        "size_bytes": 248122,
        "mime_type": "application/pdf",
        "uploaded_at": "2026-03-10T14:20:00Z",
        "linked_to": "PRESSKIT",
        "workspace_id": "ws_333c92d68a7545aa9060"
    }
]

GET /api/collections API Key

Lists collections visible to the API key. Requires `collections:read`. Collections never mix personal and workspace items.

Query Parameters

Param	Type	Default	Description
`page`	int	1	Current page number
`limit`	int	20	Max 100 items per page
`workspace_id`	string	-	Optional workspace scope. The API key must include this workspace in its allowlist.

Request Snippet

Sample JSON response

{
    "collections": [
        {
            "collection_id": "coll-123456",
            "share_code": "BNDL42",
            "context_type": "workspace",
            "workspace_id": "ws_333c92d68a7545aa9060",
            "title": "Partner Launch Kit",
            "description": "Workspace collection for approved launch assets",
            "display_mode": "grid",
            "created_at": "2026-03-12T10:30:00Z",
            "status": "active",
            "password_protected": false
        }
    ],
    "pagination": {
        "current_page": 1,
        "total_pages": 1,
        "total_items": 1,
        "page_size": 20,
        "has_next": false,
        "has_prev": false
    }
}

GET /api/links/audit/log API Key

Fetch paginated public access history for links. Requires `audit:read`. This log tracks public access and redemption events, not API key activity.

Query Parameters

Param	Type	Default	Description
`share_code`	string	-	Filter by specific sharing code
`start_date`	datetime	-	ISO 8601 (e.g. 2026-03-01T00:00:00)
`end_date`	datetime	-	ISO 8601 end date
`limit`	int	50	Max 100 logs per page
`offset`	int	0	Number of logs to skip
`search`	string	-	Search in titles or codes

Request Snippet

Sample JSON response

{
    "items": [ {
        "timestamp": "2026-03-10T14:23:00Z",
        "action": "redirect",
        "share_code": "PRESSKIT",
        "ip_address": "192.168.1.100",
        "country_code": "BE",
        "success": true
    } ],
    "total_count": 1247
}

GET /api/links/audit/export API Key

Download public access history as CSV for reporting, investigations, or SIEM-ready ingestion workflows. Requires `audit:read` and the CSV export feature.

SIEM Export Command

Sample CSV response

timestamp,action,share_code,ip_address,country_code,success
2026-03-10T14:23:00Z,redirect,PRESSKIT,192.168.1.100,BE,true
2026-03-10T14:24:12Z,redirect,PRESSKIT,8.8.8.8,US,true

GET /api/keys/audit/log Session Only

Owner governance endpoint. Reads dedicated API key activity collected by the backend. This endpoint is session-only; API keys cannot read their own activity.

Query Parameters

Param	Type	Default	Description
`api_key_prefix`	string	-	Filter by key prefix
`workspace_id`	string	-	Filter by workspace context
`start_date`	datetime	-	ISO 8601 start date
`end_date`	datetime	-	ISO 8601 end date
`limit`	int	50	Max 100 activity rows per page
`offset`	int	0	Number of rows to skip

Request Snippet

Sample JSON response

{
    "items": [ {
        "timestamp": "2026-05-18T09:42:11Z",
        "api_key_prefix": "bl_live_ab12",
        "api_key_name": "Partner sync",
        "method": "GET",
        "path": "/api/links",
        "status_code": 200,
        "workspace_id": "ws_333c92d68a7545aa9060",
        "scope": "links:read",
        "success": true
    } ],
    "total_count": 83
}

GET /api/keys/audit/export Session Only

Exports dedicated API key activity as CSV for owner review and governance evidence. Session-only by design.

SIEM Export Command

Sample CSV response

timestamp,api_key_prefix,api_key_name,method,path,status_code,workspace_id,scope,success
2026-05-18T09:42:11Z,bl_live_ab12,Partner sync,GET,/api/links,200,ws_333c92d68a7545aa9060,links:read,true
2026-05-18T09:44:01Z,bl_live_ab12,Partner sync,GET,/api/files,403,ws_blocked,files:read,false

5 Automation Recipes

6 Error Codes

HTTP Status	Error Key	Reason & Context
401	`Unauthorized`	Authentication is missing, invalid, or expired.
403	`api_scope_required`	The API key is valid but does not include the required scope for this route.
403	`workspace_forbidden`	The requested workspace is not allowlisted on the API key, or the session account is not an active workspace member.
403	`verified_required`	Identity Lock is active. Email verification is required for this account.
403	`feature_locked`	The account plan does not include the requested capability, such as CSV audit export.
404	`Not Found`	The requested resource was not found in the authenticated personal or workspace scope.
429	`Too Many Requests`	Rate limit exceeded. Back off and retry after the indicated delay.