{"openapi":"3.1.0","info":{"title":"Quidbill Agent API","version":"1.0.0","description":"Agent-operable invoice drafting API. Fiscal issuance, email sending, and payment mutation remain human-gated in the Quidbill UI."},"servers":[{"url":"https://app.quidbill.app"}],"security":[{"bearerApiKey":[]}],"paths":{"/api/agent/v1/clients":{"get":{"summary":"List or search active clients visible to the API key owner","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Clients returned"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Create an active billing client","description":"Creates durable client state. Uses the same write permission as draft invoice creation.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClientRequest"}}}},"responses":{"201":{"description":"Client created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"An active client already uses the email address"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/agent/v1/keys":{"get":{"summary":"List API keys for the signed-in user","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"API keys returned"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"summary":"Create an API key for the signed-in user","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"200":{"description":"API key created. The raw key is shown once."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/v1/keys/{id}":{"delete":{"summary":"Revoke an API key for the signed-in user","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"API key revoked"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agent/v1/invoices":{"get":{"summary":"List invoices visible to the API key owner","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/InvoiceStatus"}},{"name":"clientId","in":"query","schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"fromDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"toDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Invoices returned"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Create a draft invoice","description":"Creates a draft only. A human must review and send or issue the invoice in Quidbill.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraftInvoiceRequest"}}}},"responses":{"201":{"description":"Draft invoice created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Invoice creation blocked by entitlement or workspace rules"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/agent/v1/invoices/{id}":{"get":{"summary":"Read one invoice and its line items","parameters":[{"$ref":"#/components/parameters/IdPathParam"}],"responses":{"200":{"description":"Invoice returned"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"sb-access-token"}},"parameters":{"IdPathParam":{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}},"schemas":{"CreateApiKeyRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"permissions":{"type":"array","items":{"enum":["clients:read","invoices:read","invoices:draft:create"]}},"rateLimit":{"type":"integer","minimum":1,"maximum":1000,"default":60}}},"CreateDraftInvoiceRequest":{"type":"object","required":["clientId","currency","lines"],"oneOf":[{"required":["dueDate"],"not":{"required":["paymentTermsDays"]}},{"required":["paymentTermsDays"],"not":{"required":["dueDate"]}}],"properties":{"clientId":{"type":"integer","minimum":1},"currency":{"type":"string","enum":["AUD","CAD","EUR","GBP","USD"]},"dueDate":{"type":"string","format":"date"},"issueDate":{"type":"string","format":"date","description":"Optional non-future invoice date. Defaults to today."},"projectName":{"type":"string"},"paymentTermsDays":{"type":"integer","minimum":0,"maximum":365,"description":"Alternative to dueDate. Added to issueDate by the server."},"paymentTermsLabel":{"type":"string"},"notes":{"type":"string"},"lines":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DraftInvoiceLine"}}}},"CreateClientRequest":{"type":"object","required":["name","email","defaultCurrency","defaultPaymentTerms"],"properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email"},"companyName":{"type":"string"},"country":{"type":"string"},"taxId":{"type":"string"},"vatNumber":{"type":"string"},"defaultCurrency":{"type":"string","enum":["AUD","CAD","EUR","GBP","USD"]},"defaultPaymentTerms":{"type":"integer","minimum":0,"maximum":365,"description":"Default number of days between issue and due date."}}},"DraftInvoiceLine":{"type":"object","required":["name","quantity","unitPrice","taxRate"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number","exclusiveMinimum":0,"default":1},"unitPrice":{"type":"number","exclusiveMinimum":0},"taxRate":{"type":"number","minimum":0,"maximum":100,"default":0}}},"InvoiceStatus":{"enum":["draft","sent","paid","overdue","cancelled"]},"InvoiceAmounts":{"type":"object","required":["subtotal","taxAmount","total"],"properties":{"subtotal":{"type":"string","description":"Tax-exclusive amount in invoice currency."},"taxAmount":{"type":"string","description":"Total tax amount in invoice currency."},"total":{"type":"string","description":"Tax-inclusive invoice total."}}},"TaxBreakdown":{"type":"object","required":["taxRate","subtotal","taxAmount"],"properties":{"taxRate":{"type":"string"},"subtotal":{"type":"string"},"taxAmount":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request"},"Unauthorized":{"description":"Missing or invalid authentication"},"Forbidden":{"description":"API key does not have the required permission"},"NotFound":{"description":"Resource not found"},"RateLimited":{"description":"Hourly API key rate limit exceeded"}}}}