An API for the whole back office.

An API for the whole back office.

Every feature in Guliel is on the API. Not a marketing claim — the dashboard, the AI companion, the MCP server, and the automations engine all call the same REST endpoints. If the UI can do it, the API can do it.

REST. JSON. OAuth or PAT. Idempotency keys. Webhooks. Versioned (v1 today). Documented per route. Free tier includes the API.

Status — the public REST API is in development. The shape below is the design we're shipping; the changelog flags general-availability when it lands. Early-access keys are available on request — email hello@guliel.com.

Auth

Two options.

Personal access tokens (PAT) — for scripts, internal tools, your own infra. Issue one in the dashboard. Bearer token in the Authorization header. Scoped per org. Revocable.

OAuth 2.0 — for third-party apps acting on a user's behalf. Standard authorization-code flow. Scopes per feature area (invoices:write, expenses:read, suppliers:write, etc.). PKCE supported. The OAuth flow is the right choice for any tool a customer of yours will install.

Both methods land in the same authorization layer. Per-org permissions apply regardless of auth method.

Issue an invoice

The hello-world is one POST.

curl -X POST https://api.guliel.com/v1/invoices \
  -H "Authorization: Bearer $GULIEL_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3b9c2a-2a1e-4f6d-bd0b-1bf6c8e5a7d2" \
  -d '{
    "organizationId": "org_01J9R6V8K2",
    "customerId": "cus_01J9R7AB3M",
    "currency": "SGD",
    "issueDate": "2026-05-13",
    "dueDate": "2026-06-12",
    "items": [
      { "description": "Consulting — May 2026", "quantity": 12, "unitPrice": 250 }
    ]
  }'

Response is the canonical invoice resource — id, number (country-specific format), status, total, pdfUrl, xmlUrl if applicable (Peppol BIS / XRechnung / etc.), createdAt. The document is issued under the country standard of the issuing org: Singapore Tax Invoice with InvoiceNow-compatible Peppol BIS Billing 3.0 XML if Singapore, XRechnung if Germany, NF-e if Brazil, and so on. Same call, country-correct output. Direct transmission via Guliel acting as a Peppol Access Point lands later 2026 — until then the XML is yours to route through your existing AP or the national portal. See /invoicing for the coverage list.

Idempotency

Pass Idempotency-Key on any mutating request (POST, PUT, PATCH, DELETE). Retries with the same key in a 24-hour window return the original response. Use UUIDs.

Without an idempotency key, retries create duplicates. With one, retries are safe. We make this the developer's choice rather than guessing — opt-in is correct for an API where some clients explicitly want a fresh creation.

Sample endpoints

The full reference lives at /docs. The shape:

Resource Endpoints
Invoices POST /v1/invoices, GET /v1/invoices, GET /v1/invoices/{id}, POST /v1/invoices/{id}/send, POST /v1/invoices/{id}/cancel
Expenses POST /v1/expenses, POST /v1/expenses/scan, GET /v1/expenses, PATCH /v1/expenses/{id}
Customers POST /v1/customers, GET /v1/customers, PATCH /v1/customers/{id}
Suppliers POST /v1/suppliers, POST /v1/suppliers/{id}/orders, GET /v1/suppliers/{id}/orders/{orderId}
Items POST /v1/items, GET /v1/items, POST /v1/items/{id}/stock
Reports POST /v1/reports/{reportId}/generate, GET /v1/reports
Automations POST /v1/automations, GET /v1/automations, POST /v1/automations/{id}/replay
Organizations GET /v1/organizations, POST /v1/organizations (multi-org under one account)

Everything is org-scoped. The organizationId is required on creation calls and inferred from the resource on reads. Cross-org reads need separate calls.

Webhooks

Subscribe to events. We POST a signed payload to your URL. Standard secret-based HMAC signature in X-Guliel-Signature. Replay attack defense via timestamp tolerance window.

curl -X POST https://api.guliel.com/v1/webhooks \
  -H "Authorization: Bearer $GULIEL_PAT" \
  -d '{
    "url": "https://yourapp.com/guliel/webhook",
    "events": ["invoice.paid", "invoice.overdue", "supplier.order.invoiced"]
  }'

Webhooks deliver at-least-once. Use the event.id to dedup on your side. Failed deliveries retry with exponential backoff for 24 hours. The failure log is in the dashboard.

The full event list mirrors the automation triggers. Anything the automation engine can react to, a webhook can carry.

Rate limits

Per-org, per-method-class:

  • Reads: 100 req/sec sustained, 200 burst
  • Writes: 20 req/sec sustained, 40 burst
  • Expense scan uploads: 10 req/sec (these are expensive on our side too)

429 responses include a Retry-After header. The limits are generous for any realistic workflow and we'd rather lift the cap for a specific use case than have you architect around it — ask.

Pricing

The API is included on every tier, including free. The metering is on invoices, expense scans, AI messages, and active automations — not on API calls. Standard ($20 / org / month) unlocks unlimited automations and 5,000 invoices / month, which is where most API-driven workflows want to be. See /pricing.

FAQ

Is there an SDK?

TypeScript SDK is shipped. Python and Go are in active development. Anything else: the OpenAPI spec is published at /docs — generate a client in your language of choice. We're not going to gatekeep the API behind a curated language list.

How is this different from the MCP server?

REST is for code. MCP is for AI agents. Same actions underneath, different protocols on top. A typical backend integration uses REST. A Claude Desktop user pointing at Guliel uses MCP. Both can coexist on the same org with the same auth.

What about pagination?

Cursor-based on all list endpoints. Pass ?limit=50&cursor=... — the response includes nextCursor when more pages exist. Offset pagination isn't supported for performance reasons on large datasets.

Can I generate country-specific invoices via API?

Yes — the document standard follows from the issuing organization's country. Set the org's country once at creation; every invoice POSTed against that org uses the right standard automatically. No per-call format flag.

What's the SLA?

99.9% uptime target, monitored externally. Status page at status.guliel.com. Premium tier ($99 / org / month) adds priority support and faster incident response. No enterprise tier with custom SLAs today — that's a roadmap item once we have customers asking for it.

Is the API stable?

The v1 namespace is stable. Breaking changes ship under v2 with at least 12 months of overlap. Additive changes (new fields, new endpoints, new events) ship inside v1 without version bumps. Deprecations are announced in the changelog and emitted as a Deprecation header on responses.

Get an API key from your dashboard. Pricing at /pricing.

Last updated:

Get an API keysee pricing →