{"openapi":"3.1.0","info":{"title":"Daftra (BYOK) API","version":"0.1.0","description":"Daftra (BYOK) lets an AI assistant read your own Daftra data through the Daftra API with a key you supply (Daftra API key (Settings > API > API Key in your account)). Read-only: 12 tools (get_site_info, list_products, list_product_categories, list_stores, list_taxes, list_shipping_options, list_journal_accounts, list_journal_categories, get_reference_listing, list_follow_up_statuses,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-daftra-core.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-daftra-core/docs"},"termsOfService":"https://connectorbay.com/byok-daftra-core/terms"},"servers":[{"url":"https://byok-daftra-core.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-daftra-core/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_site_info":{"post":{"operationId":"get_site_info","summary":"Show the Daftra account the key belongs to: business name, subdomain, country, timezone id, default currency, date forma","description":"Show the Daftra account the key belongs to: business name, subdomain, country, timezone id, default currency, date format and subscription expiry. Owner contact details are left out. Use for \"Which Daftra business is my key connected to, and what is its currency\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"get_site_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_products":{"post":{"operationId":"list_products","summary":"List products and services with code, barcode, selling and cost price, stock balance, status, brand and category, sorted","description":"List products and services with code, barcode, selling and cost price, stock balance, status, brand and category, sorted by name. Filter by keyword, category, brand or supplier. Use for \"Which products are in my Daftra catalog and how many are in stock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"keywords":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over product name, code, barcode and tags.","title":"Keywords"},"category":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only products of this product category id (child categories are included by the server).","title":"Category"},"brand_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only products of this brand id (needs the Inventory feature).","title":"Brand Id"},"supplier_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only products whose default supplier has this id.","title":"Supplier Id"},"product_code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the product with exactly this product code.","title":"Product Code"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_product_categories":{"post":{"operationId":"list_product_categories","summary":"List product categories with name, parent category id and dates. parent_id 0 is a top-level category. Use for \"What prod","description":"List product categories with name, parent category id and dates. parent_id 0 is a top-level category. Use for \"What product categories does my Daftra account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"parent_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only subcategories of this parent category id.","title":"Parent Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_product_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_stores":{"post":{"operationId":"list_stores","summary":"List stores (warehouses) with name, address, whether it is the primary store, active flag and branch id. Needs the Track","description":"List stores (warehouses) with name, address, whether it is the primary store, active flag and branch id. Needs the Track Inventory or General Settings permission. Use for \"Which warehouses are set up in my Daftra account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_storesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_taxes":{"post":{"operationId":"list_taxes","summary":"List the taxes configured in the account with rate in percent, whether the tax is included in prices and whether it is a","description":"List the taxes configured in the account with rate in percent, whether the tax is included in prices and whether it is active. Not paginated. Use for \"Which tax rates are configured in my Daftra account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"is_active":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 for active taxes only, 0 for inactive taxes only; omit for all (active first).","title":"Is Active"}},"required":["subdomain"],"title":"list_taxesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_shipping_options":{"post":{"operationId":"list_shipping_options","summary":"List the active shipping options that can be added to invoices: name, fee, tax id, display order. Not paginated. Use for","description":"List the active shipping options that can be added to invoices: name, fee, tax id, display order. Not paginated. Use for \"What shipping options can I apply to Daftra invoices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_shipping_optionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_journal_accounts":{"post":{"operationId":"list_journal_accounts","summary":"List chart-of-accounts leaf accounts by code with name, nature (0 credit, 1 debit), parent category id and total debit a","description":"List chart-of-accounts leaf accounts by code with name, nature (0 credit, 1 debit), parent category id and total debit and credit posted. Needs the Manage Journal Accounts permission. Use for \"What is in my Daftra chart of accounts and what are the account balances\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"journal_cat_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only accounts under this journal category id.","title":"Journal Cat Id"},"has_cost_centers":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 for accounts linked to cost centers only, 0 for accounts without.","title":"Has Cost Centers"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_journal_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_journal_categories":{"post":{"operationId":"list_journal_categories","summary":"List chart-of-accounts category nodes with code, name, nature, parent id (-1 for top level) and accumulated debit and cr","description":"List chart-of-accounts category nodes with code, name, nature, parent id (-1 for top level) and accumulated debit and credit. Needs the Manage Journal Accounts permission. Use for \"How is my Daftra chart of accounts organised into categories\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain"],"title":"list_journal_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_reference_listing":{"post":{"operationId":"get_reference_listing","summary":"Get a small id-to-title map of one reference list: categories, invoice layouts, price lists, staff roles, time zones, la","description":"Get a small id-to-title map of one reference list: categories, invoice layouts, price lists, staff roles, time zones, languages, projects, time activities or date formats. Use for \"Which price lists and invoice layouts exist in my Daftra account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"model":{"description":"Which list: Category, InvoiceLayout, GroupPrice, Role, Timezone, Language, Project, TimeActivity or DateFormats (case-sensitive).","enum":["Category","InvoiceLayout","GroupPrice","Role","Timezone","Language","Project","TimeActivity","DateFormats"],"title":"Model","type":"string"}},"required":["subdomain","model"],"title":"get_reference_listingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_follow_up_statuses":{"post":{"operationId":"list_follow_up_statuses","summary":"List the follow-up statuses (workflow stages) defined for one record type, in display order. Needs the Edit Client Setti","description":"List the follow-up statuses (workflow stages) defined for one record type, in display order. Needs the Edit Client Settings permission. Use for \"What follow-up statuses are defined for Daftra invoices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"type":{"description":"Record type: client, invoice, estimate, purchase_order, product or work_order.","enum":["client","invoice","estimate","purchase_order","product","work_order"],"title":"Type","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["subdomain","type"],"title":"list_follow_up_statusesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product_sales_report":{"post":{"operationId":"get_product_sales_report","summary":"Run the product sales report in summary form (totals only, no invoice lines): quantity, discount, tax and total per peri","description":"Run the product sales report in summary form (totals only, no invoice lines): quantity, discount, tax and total per period, product, category or brand, per currency. Large ranges can be refused by the server; narrow the dates. Use for \"How much did I sell by product category in Daftra last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"group_by":{"anyOf":[{"enum":["daily","weekly","monthly","yearly","product","category","brand"],"type":"string"},{"type":"null"}],"default":"monthly","description":"Grouping: daily, weekly, monthly, yearly, product, category or brand.","title":"Group By"},"is_summary":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Always 1 here: summary figures per group.","title":"Is Summary"},"date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day in YYYY-MM-DD form, zero-padded.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day in YYYY-MM-DD form, zero-padded.","title":"Date To"},"currency":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"One currency code to keep, or -1 to convert everything into the base currency (one bucket).","title":"Currency"},"category":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this product category id (children included).","title":"Category"},"brand_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only this brand id.","title":"Brand Id"}},"required":["subdomain"],"title":"get_product_sales_reportArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_profit_and_loss_report":{"post":{"operationId":"get_profit_and_loss_report","summary":"Run the accrual-basis profit and loss report as a chart-of-accounts tree with one column per period: income, expenses an","description":"Run the accrual-basis profit and loss report as a chart-of-accounts tree with one column per period: income, expenses and profit totals. Defaults to the last 12 months. Use for \"What was my Daftra profit and loss by month this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Daftra account subdomain: the part before .daftara.com in your account address, for example 'mycompany'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day in YYYY-MM-DD form, zero-padded. Defaults to 11 months ago.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day in YYYY-MM-DD form, zero-padded. Defaults to one month ahead.","title":"Date To"},"group_by_date":{"anyOf":[{"enum":["monthly","quarterly","annually"],"type":"string"},{"type":"null"}],"default":"monthly","description":"Period of each column: monthly, quarterly or annually.","title":"Group By Date"},"max_level":{"anyOf":[{"maximum":7,"minimum":1,"type":"integer"},{"type":"null"}],"default":3,"description":"How deep to walk the account tree (1 to 7).","title":"Max Level"}},"required":["subdomain"],"title":"get_profit_and_loss_reportArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}