API & AI

API reference

All endpoints of the REST API with parameters and responses, generated from the OpenAPI description.

This reference is generated from the OpenAPI description of a running Annuva instance. Your own instance publishes the same document at /api/v1/openapi. Authentication and conventions are described in REST API.

Click an endpoint to see its parameters and response.

API version 1.3.0

billing

POST/api/v1/billing/runRecurring billing run (draft invoices from due recurring charges)

Recurring billing run (draft invoices from due recurring charges)

Parameters

`dryRun`	body	boolean
`until`	body	string (date)

Response

200OKobject

customers

GET/api/v1/customersList customers

List customers

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Customer[], limit: integer, offset: integer, total: integer}

POST/api/v1/customersCreate customer

Create customer

Parameters

`name`required	body	string
`channel`	body	"direct" \| "partner" \| "own_project" \| "internal"
`partnerId`	body	string (uuid) \| null
`status`	body	"active" \| "paused" \| "inactive" \| "in_preparation"
`language`	body	"de" \| "en"
`contactName`	body	string \| null
`email`	body	string (email) \| null
`phone`	body	string \| null
`billingAddress`	body	string \| null
`vatId`	body	string \| null
`hourlyRate`	body	number \| null
`hostingSummary`	body	string \| null
`notes`	body	string \| null

Response

201CreatedCustomer

GET/api/v1/customers/{id}Get customer

Get customer

Parameters

idrequired path string (uuid)

Response

200OKCustomer

PATCH/api/v1/customers/{id}Update customer

Update customer

Parameters

`id`required	path	string (uuid)
`name`	body	string
`channel`	body	"direct" \| "partner" \| "own_project" \| "internal"
`partnerId`	body	string (uuid) \| null
`status`	body	"active" \| "paused" \| "inactive" \| "in_preparation"
`language`	body	"de" \| "en"
`contactName`	body	string \| null
`email`	body	string (email) \| null
`phone`	body	string \| null
`billingAddress`	body	string \| null
`vatId`	body	string \| null
`hourlyRate`	body	number \| null
`hostingSummary`	body	string \| null
`notes`	body	string \| null

Response

200OKCustomer

DELETE/api/v1/customers/{id}Delete customer

Delete customer

Parameters

idrequired path string (uuid)

Response

204Deleted

POST/api/v1/customers/{id}/archiveArchive customer

Archive customer

Parameters

idrequired path string (uuid)

Response

200OKCustomer

DELETE/api/v1/customers/{id}/archiveRestore archived customer

Restore archived customer

Parameters

idrequired path string (uuid)

Response

200OKCustomer

dashboard

GET/api/v1/dashboardDashboard data

Dashboard data

Parameters

`year`	query	integer
`customer`	query	string (uuid)

Response

200OKobject

expenses

GET/api/v1/expensesList expenses

List expenses

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Expense[], limit: integer, offset: integer, total: integer}

POST/api/v1/expensesCreate expense

Create expense

Parameters

`date`required	body	string
`vendor`required	body	string
`item`required	body	string
`category`required	body	"server" \| "domain" \| "package" \| "license" \| "hardware" \| "software" \| "service" \| "travel" \| "office" \| "other"
`assignedTo`required	body	string (uuid)
`grossAmount`required	body	number
`originalAmount`	body	number \| null
`originalCurrency`	body	string \| null
`status`	body	"receipt" \| "expected" \| "planned"
`receiptFileId`	body	string (uuid) \| null

Response

201CreatedExpense

GET/api/v1/expenses/{id}Get expense

Get expense

Parameters

idrequired path string (uuid)

Response

200OKExpense

PATCH/api/v1/expenses/{id}Update expense

Update expense

Parameters

`id`required	path	string (uuid)
`date`	body	string
`vendor`	body	string
`item`	body	string
`category`	body	"server" \| "domain" \| "package" \| "license" \| "hardware" \| "software" \| "service" \| "travel" \| "office" \| "other"
`assignedTo`	body	string (uuid)
`grossAmount`	body	number
`originalAmount`	body	number \| null
`originalCurrency`	body	string \| null
`status`	body	"receipt" \| "expected" \| "planned"
`receiptFileId`	body	string (uuid) \| null

Response

200OKExpense

DELETE/api/v1/expenses/{id}Delete expense

Delete expense

Parameters

idrequired path string (uuid)

Response

204Deleted

files

POST/api/v1/filesUpload a file

Upload a file

Parameters

file body string (binary)

Response

201Stored fileobject

GET/api/v1/files/{id}Download a file

Download a file

Parameters

idrequired path string (uuid)

Response

200File content

invoice-templates

GET/api/v1/invoice-templatesList invoiceTemplates

List invoiceTemplates

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: InvoiceTemplate[], limit: integer, offset: integer, total: integer}

POST/api/v1/invoice-templatesCreate invoice template

Create invoice template

Parameters

`name`required	body	string
`isDefault`	body	boolean \| null
`logoFileId`	body	string (uuid) \| null
`senderLine`	body	string \| null
`introText`	body	string \| null
`closingText`	body	string \| null
`signatureFileId`	body	string (uuid) \| null
`signatureName`	body	string \| null
`footerLeft`	body	string \| null
`footerCenter`	body	string \| null
`footerRight`	body	string \| null
`accentColor`	body	string \| null
`paymentTermDays`	body	integer

Response

201CreatedInvoiceTemplate

GET/api/v1/invoice-templates/{id}Get invoice template

Get invoice template

Parameters

idrequired path string (uuid)

Response

200OKInvoiceTemplate

PATCH/api/v1/invoice-templates/{id}Update invoice template

Update invoice template

Parameters

`id`required	path	string (uuid)
`name`	body	string
`isDefault`	body	boolean \| null
`logoFileId`	body	string (uuid) \| null
`senderLine`	body	string \| null
`introText`	body	string \| null
`closingText`	body	string \| null
`signatureFileId`	body	string (uuid) \| null
`signatureName`	body	string \| null
`footerLeft`	body	string \| null
`footerCenter`	body	string \| null
`footerRight`	body	string \| null
`accentColor`	body	string \| null
`paymentTermDays`	body	integer

Response

200OKInvoiceTemplate

DELETE/api/v1/invoice-templates/{id}Delete invoice template

Delete invoice template

Parameters

idrequired path string (uuid)

Response

204Deleted

POST/api/v1/invoice-templates/previewPreview an invoice template – also unsaved values – as a sample invoice (admin)

Preview an invoice template – also unsaved values – as a sample invoice (admin)

Parameters

`name`	body	string
`isDefault`	body	boolean \| null
`logoFileId`	body	string (uuid) \| null
`senderLine`	body	string \| null
`introText`	body	string \| null
`closingText`	body	string \| null
`signatureFileId`	body	string (uuid) \| null
`signatureName`	body	string \| null
`footerLeft`	body	string \| null
`footerCenter`	body	string \| null
`footerRight`	body	string \| null
`accentColor`	body	string \| null
`paymentTermDays`	body	integer

Response

200Sample invoice as PDF

invoices

GET/api/v1/invoicesList invoices

List invoices

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Invoice[], limit: integer, offset: integer, total: integer}

POST/api/v1/invoicesCreate draft invoice

Create draft invoice

Parameters

`customerId`required	body	string (uuid)
`description`required	body	string
`dueDate`	body	string \| null
`language`	body	"de" \| "en"
`lines`required	body	object[]
`notes`	body	string \| null
`partnerId`	body	string (uuid) \| null
`recipientType`	body	"customer" \| "partner"
`serviceDateFrom`	body	string \| null
`serviceDateTo`	body	string \| null
`templateId`	body	string (uuid) \| null

Response

201Draft createdInvoice

GET/api/v1/invoices/{id}Get invoice

Get invoice

Parameters

idrequired path string (uuid)

Response

200OKInvoice

PATCH/api/v1/invoices/{id}Update draft invoice

Update draft invoice

Parameters

`id`required	path	string (uuid)
`customerId`	body	string (uuid)
`description`	body	string
`dueDate`	body	string \| null
`language`	body	"de" \| "en"
`lines`	body	object[]
`notes`	body	string \| null
`partnerId`	body	string (uuid) \| null
`recipientType`	body	"customer" \| "partner"
`serviceDateFrom`	body	string \| null
`serviceDateTo`	body	string \| null
`templateId`	body	string (uuid) \| null

Response

200OKInvoice

DELETE/api/v1/invoices/{id}Delete draft invoice

Delete draft invoice

Parameters

idrequired path string (uuid)

Response

204Deleted

POST/api/v1/invoices/{id}/issueIssue invoice (number, PDF)

Issue invoice (number, PDF)

Parameters

`id`required	path	string (uuid)
`date`	body	string (date)

Response

200OKInvoice

POST/api/v1/invoices/{id}/payMark as paid

Mark as paid

Parameters

`id`required	path	string (uuid)
`paidAt`	body	string (date)

Response

200OKInvoice

POST/api/v1/invoices/{id}/reopenPaid → open

Paid → open

Parameters

idrequired path string (uuid)

Response

200OKInvoice

POST/api/v1/invoices/{id}/cancelCancel via cancellation invoice

Cancel via cancellation invoice

Parameters

idrequired path string (uuid)

Response

200OKInvoice

POST/api/v1/invoices/{id}/sendSend by e-mail

Send by e-mail

Parameters

`id`required	path	string (uuid)
`message`	body	string
`to`	body	string (email)

Response

200OKInvoice

POST/api/v1/invoices/{id}/remindSend payment reminder

Send payment reminder

Parameters

`id`required	path	string (uuid)
`message`	body	string
`to`	body	string (email)

Response

200OKInvoice

GET/api/v1/invoices/{id}/pdfInvoice PDF (draft preview or stored PDF)

Invoice PDF (draft preview or stored PDF)

Parameters

idrequired path string (uuid)

Response

200PDF

offers

GET/api/v1/offersList offers

List offers

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Offer[], limit: integer, offset: integer, total: integer}

POST/api/v1/offersCreate offer

Create offer

Parameters

`customerId`required	body	string (uuid)
`number`required	body	string
`date`required	body	string
`validUntil`	body	string \| null
`amount`required	body	number
`status`	body	"open" \| "accepted" \| "rejected"
`description`	body	string \| null
`fileId`	body	string (uuid) \| null

Response

201CreatedOffer

GET/api/v1/offers/{id}Get offer

Get offer

Parameters

idrequired path string (uuid)

Response

200OKOffer

PATCH/api/v1/offers/{id}Update offer

Update offer

Parameters

`id`required	path	string (uuid)
`customerId`	body	string (uuid)
`number`	body	string
`date`	body	string
`validUntil`	body	string \| null
`amount`	body	number
`status`	body	"open" \| "accepted" \| "rejected"
`description`	body	string \| null
`fileId`	body	string (uuid) \| null

Response

200OKOffer

DELETE/api/v1/offers/{id}Delete offer

Delete offer

Parameters

idrequired path string (uuid)

Response

204Deleted

partners

GET/api/v1/partnersList partners

List partners

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Partner[], limit: integer, offset: integer, total: integer}

POST/api/v1/partnersCreate partner

Create partner

Parameters

`name`required	body	string
`email`	body	string (email) \| null
`billingAddress`	body	string \| null
`notes`	body	string \| null

Response

201CreatedPartner

GET/api/v1/partners/{id}Get partner

Get partner

Parameters

idrequired path string (uuid)

Response

200OKPartner

PATCH/api/v1/partners/{id}Update partner

Update partner

Parameters

`id`required	path	string (uuid)
`name`	body	string
`email`	body	string (email) \| null
`billingAddress`	body	string \| null
`notes`	body	string \| null

Response

200OKPartner

DELETE/api/v1/partners/{id}Delete partner

Delete partner

Parameters

idrequired path string (uuid)

Response

204Deleted

profile

GET/api/v1/profileOwn profile

Own profile

Parameters

No parameters.

Response

200OKobject

PATCH/api/v1/profileUpdate own profile

Update own profile

Parameters

No parameters.

Response

200OKobject

GET/api/v1/profile/two-factorTwo-factor status of the own account

Two-factor status of the own account

Parameters

No parameters.

Response

200OK{enabled: boolean, recoveryCodesLeft: integer}

GET/api/v1/tokensOwn API tokens

Own API tokens

Parameters

No parameters.

Response

200OKobject

POST/api/v1/tokensCreate API token

Create API token

Parameters

No parameters.

Response

201Token (shown once)

recurring-charges

GET/api/v1/recurring-chargesList recurringCharges

List recurringCharges

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: RecurringCharge[], limit: integer, offset: integer, total: integer}

POST/api/v1/recurring-chargesCreate recurring charge

Create recurring charge

Parameters

`customerId`required	body	string (uuid)
`service`required	body	"hosting" \| "domain" \| "package" \| "maintenance" \| "other"
`description`	body	string \| null
`amountPerYear`required	body	number
`interval`	body	"yearly" \| "quarterly" \| "monthly"
`nextInvoiceDate`required	body	string
`startsAfterSetup`	body	boolean \| null

Response

201CreatedRecurringCharge

GET/api/v1/recurring-charges/{id}Get recurring charge

Get recurring charge

Parameters

idrequired path string (uuid)

Response

200OKRecurringCharge

PATCH/api/v1/recurring-charges/{id}Update recurring charge

Update recurring charge

Parameters

`id`required	path	string (uuid)
`customerId`	body	string (uuid)
`service`	body	"hosting" \| "domain" \| "package" \| "maintenance" \| "other"
`description`	body	string \| null
`amountPerYear`	body	number
`interval`	body	"yearly" \| "quarterly" \| "monthly"
`nextInvoiceDate`	body	string
`startsAfterSetup`	body	boolean \| null

Response

200OKRecurringCharge

DELETE/api/v1/recurring-charges/{id}Delete recurring charge

Delete recurring charge

Parameters

idrequired path string (uuid)

Response

204Deleted

recurring-costs

GET/api/v1/recurring-costsList recurringCosts

List recurringCosts

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: RecurringCost[], limit: integer, offset: integer, total: integer}

POST/api/v1/recurring-costsCreate recurring cost

Create recurring cost

Parameters

`name`required	body	string
`type`required	body	"domain" \| "package" \| "server" \| "other"
`provider`required	body	string
`assignedTo`required	body	string (uuid)
`costPerYear`required	body	number
`rebilledPerYear`	body	number
`nextRenewal`	body	string \| null
`autoRenew`	body	boolean \| null
`endsAt`	body	string \| null

Response

201CreatedRecurringCost

GET/api/v1/recurring-costs/{id}Get recurring cost

Get recurring cost

Parameters

idrequired path string (uuid)

Response

200OKRecurringCost

PATCH/api/v1/recurring-costs/{id}Update recurring cost

Update recurring cost

Parameters

`id`required	path	string (uuid)
`name`	body	string
`type`	body	"domain" \| "package" \| "server" \| "other"
`provider`	body	string
`assignedTo`	body	string (uuid)
`costPerYear`	body	number
`rebilledPerYear`	body	number
`nextRenewal`	body	string \| null
`autoRenew`	body	boolean \| null
`endsAt`	body	string \| null

Response

200OKRecurringCost

DELETE/api/v1/recurring-costs/{id}Delete recurring cost

Delete recurring cost

Parameters

idrequired path string (uuid)

Response

204Deleted

resources

GET/api/v1/resourcesList resources

List resources

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Resource[], limit: integer, offset: integer, total: integer}

POST/api/v1/resourcesCreate resource

Create resource

Parameters

`customerId`required	body	string (uuid)
`kind`required	body	"domain" \| "container" \| "proxy_host" \| "package" \| "server" \| "other"
`name`required	body	string
`location`	body	string \| null
`details`	body	string \| null
`externalRef`	body	string \| null

Response

201CreatedResource

GET/api/v1/resources/{id}Get resource

Get resource

Parameters

idrequired path string (uuid)

Response

200OKResource

PATCH/api/v1/resources/{id}Update resource

Update resource

Parameters

`id`required	path	string (uuid)
`customerId`	body	string (uuid)
`kind`	body	"domain" \| "container" \| "proxy_host" \| "package" \| "server" \| "other"
`name`	body	string
`location`	body	string \| null
`details`	body	string \| null
`externalRef`	body	string \| null

Response

200OKResource

DELETE/api/v1/resources/{id}Delete resource

Delete resource

Parameters

idrequired path string (uuid)

Response

204Deleted

settings

GET/api/v1/settingsBusiness settings

Business settings

Parameters

No parameters.

Response

200OKSettings

PATCH/api/v1/settingsUpdate settings (admin)

Update settings (admin)

Parameters

`name`	body	string
`companyName`	body	string \| null
`address`	body	string \| null
`email`	body	string (email) \| null
`phone`	body	string \| null
`website`	body	string \| null
`taxNumber`	body	string \| null
`vatId`	body	string \| null
`bankName`	body	string \| null
`iban`	body	string \| null
`bic`	body	string \| null
`vatMode`	body	"small_business" \| "regular"
`defaultVatRate`	body	number
`currency`	body	string
`locale`	body	"de-DE" \| "de-AT" \| "de-CH" \| "en-GB" \| "en-US"
`timezone`	body	string
`defaultHourlyRate`	body	number
`defaultHostingPerYear`	body	number
`invoiceNumberFormat`	body	string
`recurringInvoiceMonth`	body	integer
`taxPaymentMonth`	body	integer
`serverCostAllocation`	body	"equal_among_hosting_customers" \| "none"
`domainPassThrough`	body	"at_cost" \| "markup"

Response

200OKSettings

system

GET/api/healthHealth check

Health check

Parameters

No parameters.

Response

200Healthy

POST/api/mcpMCP server (Streamable HTTP, JSON-RPC)

MCP server (Streamable HTTP, JSON-RPC)

Parameters

No parameters.

Response

200MCP response

tasks

GET/api/v1/tasksList tasks

List tasks

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: Task[], limit: integer, offset: integer, total: integer}

POST/api/v1/tasksCreate task

Create task

Parameters

`title`required	body	string
`dueDate`	body	string \| null
`customerId`	body	string (uuid) \| null
`status`	body	"open" \| "waiting_for_go" \| "done"
`note`	body	string \| null

Response

201CreatedTask

GET/api/v1/tasks/{id}Get task

Get task

Parameters

idrequired path string (uuid)

Response

200OKTask

PATCH/api/v1/tasks/{id}Update task

Update task

Parameters

`id`required	path	string (uuid)
`title`	body	string
`dueDate`	body	string \| null
`customerId`	body	string (uuid) \| null
`status`	body	"open" \| "waiting_for_go" \| "done"
`note`	body	string \| null

Response

200OKTask

DELETE/api/v1/tasks/{id}Delete task

Delete task

Parameters

idrequired path string (uuid)

Response

204Deleted

tax-adjustments

GET/api/v1/tax-adjustmentsList taxAdjustments

List taxAdjustments

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: TaxAdjustment[], limit: integer, offset: integer, total: integer}

POST/api/v1/tax-adjustmentsCreate tax adjustment

Create tax adjustment

Parameters

`year`required	body	integer
`description`required	body	string
`profitAdjustment`required	body	number

Response

201CreatedTaxAdjustment

GET/api/v1/tax-adjustments/{id}Get tax adjustment

Get tax adjustment

Parameters

idrequired path string (uuid)

Response

200OKTaxAdjustment

PATCH/api/v1/tax-adjustments/{id}Update tax adjustment

Update tax adjustment

Parameters

`id`required	path	string (uuid)
`year`	body	integer
`description`	body	string
`profitAdjustment`	body	number

Response

200OKTaxAdjustment

DELETE/api/v1/tax-adjustments/{id}Delete tax adjustment

Delete tax adjustment

Parameters

idrequired path string (uuid)

Response

204Deleted

tax-years

GET/api/v1/tax-yearsList taxYears

List taxYears

Parameters

`limit`	query	integer
`offset`	query	integer
`sort`	query	string
`order`	query	"asc" \| "desc"
`q`	query	string
`customerId`	query	string (uuid)
`filter[field]`	query	string	Equality filter, e.g. filter[status]=open

Response

200OK{items: TaxYear[], limit: integer, offset: integer, total: integer}

POST/api/v1/tax-yearsCreate tax year

Create tax year

Parameters

`year`required	body	integer
`marginalRatePercent`	body	number \| null
`profitPerAssessment`	body	number \| null

Response

201CreatedTaxYear

GET/api/v1/tax-years/{id}Get tax year

Get tax year

Parameters

idrequired path string (uuid)

Response

200OKTaxYear

PATCH/api/v1/tax-years/{id}Update tax year

Update tax year

Parameters

`id`required	path	string (uuid)
`year`	body	integer
`marginalRatePercent`	body	number \| null
`profitPerAssessment`	body	number \| null

Response

200OKTaxYear

DELETE/api/v1/tax-years/{id}Delete tax year

Delete tax year

Parameters

idrequired path string (uuid)

Response

204Deleted

users

GET/api/v1/usersList users (admin)

List users (admin)

Parameters

No parameters.

Response

200OKobject

POST/api/v1/usersCreate user (admin)

Create user (admin)

Parameters

No parameters.

Response

201Created

PATCH/api/v1/users/{id}Update user (admin)

Update user (admin)

Parameters

idrequired path string (uuid)

Response

200OKobject

DELETE/api/v1/users/{id}Delete user (admin)

Delete user (admin)

Parameters

idrequired path string (uuid)

Response

204Deleted

DELETE/api/v1/users/{id}/two-factorReset two-factor authentication of a user (admin)

Reset two-factor authentication of a user (admin)

Parameters

idrequired path string (uuid)

Response

204Two-factor authentication switched off

Edit this page on GitHub