Skip to content
GinumGinumDevelopers

List safe account definitions

Draft contract · no live API. Generated from OpenAPI 3.1.1, version 1.0.0-draft.

Download the exact YAML. SHA-256: edb36682e0c124e1a67cfc6213ed93dcfa2494e84c63f79181ae7ed12f9851e7.

GET /api/v1/companies/{companyId}/ledger/accounts

Section titled “GET /api/v1/companies/{companyId}/ledger/accounts”

Operation ID: listLedgerAccounts

DRAFT pending owner decision. Revalidate live authority on each page; safe projection only. Stable order (code,id).

Authorization

Section titled “Authorization”

Alternatives below are OR choices; scopes within each choice are required together.

[
  {
    "DelegatedOAuth": [
      "ledger.accounts:read"
    ]
  },
  {
    "MachineOAuth": [
      "ledger.accounts:read"
    ]
  }
]

Ownership and limits

Section titled “Ownership and limits”
{
  "x-domain-owner": "Ledger",
  "x-permissions": [
    "ledger.coa.view"
  ],
  "x-modules": [
    "ledger"
  ],
  "x-data-classification": "Tenant-confidential safe business projection",
  "x-audit-class": "api.read",
  "x-limits": {
    "requestsPerMinute": 300,
    "burst": 30,
    "concurrency": 10
  }
}

Parameters

Section titled “Parameters”

companyId

Section titled “companyId”

path · required

Company must belong to token tenant and current installation/principal scope. Inaccessible and absent companies return indistinguishable 404.

{
  "type": "string",
  "format": "uuid"
}

limit

Section titled “limit”

query · optional

Page size, default 50/max 200; unknown query fields rejected.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}

cursor

Section titled “cursor”

query · optional

Opaque cursor from prior page. Repeat the same limit and filters; tampering or changed filters is 400 INVALID_CURSOR; expired snapshot is 409 CURSOR_EXPIRED.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 2048
}

Responses

Section titled “Responses”

200

Section titled “200”

Current authorized snapshot page.

Content type: application/json

AccountsPage

{
  "$ref": "#/components/schemas/AccountsPage"
}

200 LK example

Section titled “200 LK example”

LK synthetic fixture; no real company or tax assertion

{
  "items": [
    {
      "id": "11000000-0000-4000-8000-000000000001",
      "companyId": "10000000-0000-4000-8000-000000000001",
      "code": "1010",
      "name": "General clearing",
      "type": "ASSET",
      "status": "ACTIVE",
      "isGroup": false,
      "draftEligible": true
    },
    {
      "id": "11000000-0000-4000-8000-000000000002",
      "companyId": "10000000-0000-4000-8000-000000000001",
      "code": "5010",
      "name": "Office supplies",
      "type": "EXPENSE",
      "status": "ACTIVE",
      "isGroup": false,
      "draftEligible": true
    }
  ],
  "nextCursor": null,
  "asOf": "2026-11-06T08:00:00Z"
}

200 SG example

Section titled “200 SG example”

SG synthetic fixture; no real company or tax assertion

{
  "items": [
    {
      "id": "21000000-0000-4000-8000-000000000001",
      "companyId": "20000000-0000-4000-8000-000000000001",
      "code": "1010",
      "name": "General clearing",
      "type": "ASSET",
      "status": "ACTIVE",
      "isGroup": false,
      "draftEligible": true
    },
    {
      "id": "21000000-0000-4000-8000-000000000002",
      "companyId": "20000000-0000-4000-8000-000000000001",
      "code": "5010",
      "name": "Office supplies",
      "type": "EXPENSE",
      "status": "ACTIVE",
      "isGroup": false,
      "draftEligible": true
    }
  ],
  "nextCursor": null,
  "asOf": "2026-11-06T08:00:00Z"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  }
}

400

Section titled “400”

Malformed request, unknown fields, invalid cursor, conflicting tenant/company headers or missing/invalid Idempotency-Key.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:invalid-request",
  "title": "Invalid request",
  "status": 400,
  "code": "INVALID_REQUEST",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  }
}

401

Section titled “401”

Missing/expired/invalid/wrong issuer or audience token; ID tokens are not API credentials.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:auth-required",
  "title": "Auth required",
  "status": 401,
  "code": "AUTH_REQUIRED",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "WWW-Authenticate": {
    "description": "Bearer challenge with no sensitive details.",
    "schema": {
      "type": "string"
    },
    "example": "Bearer realm=\"ginum-api\", error=\"invalid_token\""
  }
}

403

Section titled “403”

Operation denied by current scope/grant/module policy; machine writes forbidden. No confidential resource existence disclosed.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:scope-denied",
  "title": "Scope denied",
  "status": 403,
  "code": "SCOPE_DENIED",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  }
}

404

Section titled “404”

Resource absent or inaccessible; identical response shape.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:not-found-or-denied",
  "title": "Not found or denied",
  "status": 404,
  "code": "NOT_FOUND_OR_DENIED",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  }
}

409

Section titled “409”

IDEMPOTENCY_CONFLICT for changed payload, IDEMPOTENCY_IN_PROGRESS (retryable), IDEMPOTENCY_EXPIRED (not retryable), or CURSOR_EXPIRED (restart pagination).

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:idempotency-conflict",
  "title": "Idempotency conflict",
  "status": 409,
  "code": "IDEMPOTENCY_CONFLICT",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "Retry-After": {
    "description": "Present only for IDEMPOTENCY_IN_PROGRESS; integer delay seconds. Other conflicts are not automatically retried.",
    "schema": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300
    }
  }
}

429

Section titled “429”

Quota exhausted; bounded retry only after Retry-After.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:rate-limited",
  "title": "Rate limited",
  "status": 429,
  "code": "RATE_LIMITED",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": true,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "Retry-After": {
    "description": "Nonnegative integer delay seconds, bounded at 300.",
    "schema": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300
    },
    "example": 30
  }
}

500

Section titled “500”

Unexpected failure; no implementation details. A write outcome may be uncertain; reconcile by retrying the same key only.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:internal-error",
  "title": "Internal error",
  "status": 500,
  "code": "INTERNAL_ERROR",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": false,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  }
}

503

Section titled “503”

Dependency, authorization freshness, audit or quota authority unavailable; fail closed.

Content type: application/problem+json

Problem

{
  "$ref": "#/components/schemas/Problem"
}

Example:

{
  "type": "urn:ginum:problem:temporarily-unavailable",
  "title": "Temporarily unavailable",
  "status": 503,
  "code": "TEMPORARILY_UNAVAILABLE",
  "requestId": "90000000-0000-4000-8000-000000000001",
  "retryable": true,
  "instance": "urn:uuid:90000000-0000-4000-8000-000000000001"
}

Response headers:

{
  "X-Request-Id": {
    "description": "Server-generated UUID correlation ID. New per HTTP attempt, including idempotent replay.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  "Cache-Control": {
    "description": "No shared or private response caching.",
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  },
  "X-RateLimit-Limit": {
    "description": "Proposed custom quota header: current caller bucket capacity per 60-second window; no other tenant usage.",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  "X-RateLimit-Remaining": {
    "description": "Remaining requests in current caller bucket.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "X-RateLimit-Reset": {
    "description": "Seconds until this caller bucket resets.",
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  "Retry-After": {
    "description": "Nonnegative integer delay seconds, bounded at 300.",
    "schema": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300
    },
    "example": 30
  }
}