API Reference

Base URL

All API requests are made to:

https://api.aikraft.eu/v1

The API is available on Starter plans and above. Free plan users do not have API access.

---

Authentication

Aikraft uses API keys transmitted as Bearer tokens. To generate an API key:

1. Go to Settings > API Keys in your workspace.
2. Click Generate New Key.
3. Give the key a descriptive name (e.g., ci-pipeline-prod) and select its permission scope: Read, Read/Write, or Admin.
4. Copy the key immediately — it is shown only once.

Include the key in the Authorization header of every request:

Authorization: Bearer ak_live_your_api_key_here

Keys beginning with ak_live_ are production keys. Use ak_test_ keys (generated from the same screen) for development and testing — test keys operate against a sandboxed copy of your workspace data and do not affect production records.

---

Rate Limits

Plan	Requests per minute	Burst limit
Starter	100	150
Pro	500	750
Enterprise	Custom	Custom

When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait before retrying. Responses include the following rate limit headers on every request:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1744567890

---

Error Codes

HTTP status	Error code	Meaning
400	invalid_request	Missing or malformed request body
401	unauthorized	Invalid or missing API key
403	forbidden	API key lacks permission for this action
404	not_found	Resource does not exist in your workspace
409	conflict	A system with this name already exists
422	unprocessable	Request body is valid JSON but fails validation
429	rate_limit_exceeded	Too many requests
500	internal_error	Aikraft server error — contact support if this persists

All error responses follow this structure:

{
  "error": {
    "code": "not_found",
    "message": "AI system with ID sys_abc123 was not found in this workspace.",
    "request_id": "req_9f3a2b1c"
  }
}

---

Endpoints

GET /systems

Returns a list of all AI systems in your workspace.

Request

GET https://api.aikraft.eu/v1/systems
Authorization: Bearer ak_live_your_api_key_here

Query parameters

Parameter	Type	Description
risk_tier	string	Filter by tier: unacceptable, high, limited, minimal
limit	integer	Number of results per page (default: 20, max: 100)
cursor	string	Pagination cursor from previous response

Response

{
  "data": [
    {
      "id": "sys_abc123",
      "name": "Candidate Screening Model v2",
      "domain": "Human Resources / Employment",
      "risk_tier": "high",
      "annex_iii_category": 4,
      "classification_date": "2026-03-15T10:42:00Z",
      "documentation_score": 87,
      "created_at": "2026-03-14T09:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "cursor": null
  }
}

---

POST /systems

Registers a new AI system in your workspace.

Request

POST https://api.aikraft.eu/v1/systems
Authorization: Bearer ak_live_your_api_key_here
Content-Type: application/json

{
  "name": "Loan Approval Engine",
  "description": "Scores personal loan applications using applicant financial history and behavioural data.",
  "purpose": "Automate initial credit decisions to reduce processing time",
  "domain": "Financial Services / Credit Assessment"
}

Response — 201 Created

{
  "data": {
    "id": "sys_def456",
    "name": "Loan Approval Engine",
    "domain": "Financial Services / Credit Assessment",
    "risk_tier": null,
    "classification_date": null,
    "created_at": "2026-04-13T14:30:00Z"
  }
}

risk_tier is null until classification is run. Use GET /systems/:id/classification after running the questionnaire via the UI, or trigger classification programmatically via the classification endpoint (Enterprise plan).

---

GET /systems/:id/classification

Returns the current risk classification for a system.

Request

GET https://api.aikraft.eu/v1/systems/sys_abc123/classification
Authorization: Bearer ak_live_your_api_key_here

Response

{
  "data": {
    "system_id": "sys_abc123",
    "risk_tier": "high",
    "annex_iii_category": 4,
    "annex_iii_sub_point": "4(a)",
    "confidence": "high",
    "key_factors": [
      "System output influences employment decisions affecting individuals",
      "Output is used to rank and filter applicants from a pool",
      "Human override is possible but uncommon in practice"
    ],
    "obligations": [
      "Annex IV technical documentation required",
      "Conformity assessment required before deployment",
      "Registration in EU AI Act database required",
      "Human oversight measures must be implemented"
    ],
    "classified_at": "2026-03-15T10:42:00Z",
    "version": 2
  }
}

---

POST /systems/:id/documents

Triggers generation of Annex IV technical documentation for the specified system. The system must already be classified. Returns immediately with a job ID; poll the job status endpoint for completion.

Request

POST https://api.aikraft.eu/v1/systems/sys_abc123/documents
Authorization: Bearer ak_live_your_api_key_here
Content-Type: application/json

{
  "sections": ["all"],
  "language": "en"
}

sections accepts "all" or an array of section numbers (e.g., [1, 2, 6]). language defaults to "en"; "de", "fr", and "nl" are also supported.

Response — 202 Accepted

{
  "data": {
    "job_id": "job_xyz789",
    "status": "queued",
    "estimated_seconds": 60,
    "poll_url": "https://api.aikraft.eu/v1/jobs/job_xyz789"
  }
}

---

GET /systems/:id/monitoring

Returns the current monitoring status and recent alerts for a system.

Request

GET https://api.aikraft.eu/v1/systems/sys_abc123/monitoring
Authorization: Bearer ak_live_your_api_key_here

Response

{
  "data": {
    "system_id": "sys_abc123",
    "monitoring_active": true,
    "last_checked_at": "2026-04-13T13:00:00Z",
    "overall_health": "warning",
    "alerts": [
      {
        "id": "alert_001",
        "type": "data_drift",
        "severity": "warning",
        "metric": "PSI",
        "value": 0.23,
        "threshold": 0.2,
        "feature": "years_of_experience",
        "triggered_at": "2026-04-13T11:15:00Z",
        "resolved": false
      }
    ],
    "incident_count_30d": 0,
    "documentation_score": 87,
    "days_since_last_review": 29
  }
}

overall_health is "healthy", "warning", or "critical" based on the highest-severity unresolved alert.