{ "openapi": "3.1.2", "info": { "title": "Bill.DO API v1", "version": "1.0.0", "description": "Insights into the spend of the DigitalOcean accounts connected to the team: usage and predictions, usage history, projects, resources, invoices and billing alerts." }, "servers": [ { "url": "https:\/\/bill.do\/api\/v1" } ], "tags": [ { "name": "Team", "description": "The team the request acts on, with its plan limits and their usage." }, { "name": "Accounts", "description": "The DigitalOcean accounts connected to the team. Projects, resources, usage, invoices and alerts all belong to an account." }, { "name": "Usage", "description": "What the resources of an account cost: current spend, predictions and history." }, { "name": "Projects", "description": "The DigitalOcean projects of an account. The spend per project needs a plan with the project filter." }, { "name": "Resources", "description": "The billable DigitalOcean resources of an account: apps, databases, droplets, load balancers, snapshots and volumes." }, { "name": "Invoices", "description": "The DigitalOcean invoices of an account, imported by Bill.DO." }, { "name": "Alerts", "description": "Billing alerts email the members of the team that have access to an account when its spend exceeds a limit, and again once it drops below the limit." } ], "security": [ { "ctp": [] }, { "openid": [] }, { "ctt": [] } ], "paths": { "\/team": { "get": { "operationId": "team.single", "description": "Get the team the token acts on, with its plan limits and their usage. Any Bill.DO read scope grants access.", "summary": "Get the team", "tags": [ "Team" ], "responses": { "200": { "description": "`Team`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Team" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "openid": [ "billdo:invoices:read" ] }, { "openid": [ "billdo:alerts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:invoices:read" ] }, { "ctp": [ "billdo:alerts:read" ] }, { "ctt": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:invoices:read" ] }, { "ctt": [ "billdo:alerts:read" ] } ] } }, "\/accounts": { "get": { "operationId": "accounts.index", "description": "List the DigitalOcean accounts connected to the team by name. Any Bill.DO read scope grants access.", "summary": "List accounts", "tags": [ "Accounts" ], "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Account`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Account" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "openid": [ "billdo:invoices:read" ] }, { "openid": [ "billdo:alerts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:invoices:read" ] }, { "ctp": [ "billdo:alerts:read" ] }, { "ctt": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:invoices:read" ] }, { "ctt": [ "billdo:alerts:read" ] } ] } }, "\/accounts\/{account}\/usage": { "get": { "operationId": "accounts.usage", "description": "Calculate the current spend of the account and the predicted spend for today, this month and next month, in USD. Optionally only for a project or some resource types.", "summary": "Get the usage", "tags": [ "Usage" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "project", "in": "query", "description": "Only count the usage of this DigitalOcean project UUID. Needs a plan with the project filter.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" }, { "name": "resource_types[]", "in": "query", "schema": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "app", "volume", "droplet", "database", "snapshot", "load_balancer" ] }, "minItems": 1, "uniqueItems": true } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "integer", "examples": [ 42 ] }, "project_id": { "type": "string", "description": "The project the usage is limited to, null for the whole account." }, "resource_types": { "type": [ "array", "null" ], "description": "The resource types the usage is limited to, null for all types.", "items": { "type": "string" } }, "hourly": { "type": "number", "description": "Current spend per hour of the resources that exist." }, "day_to_date": { "type": "number", "description": "Spend so far today." }, "day_predicted": { "type": "number", "description": "Predicted spend for the whole of today." }, "month_to_date": { "type": "number", "description": "Spend so far this month." }, "month_predicted": { "type": "number", "description": "Predicted spend for the whole of this month." }, "next_month_predicted": { "type": "number", "description": "Predicted spend for next month when the current resources keep running." }, "calculated_at": { "type": "string" } }, "required": [ "account_id", "project_id", "resource_types", "hourly", "day_to_date", "day_predicted", "month_to_date", "month_predicted", "next_month_predicted", "calculated_at" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "The monthly spend is above the plan limit, or the plan does not include the project filter.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "spend_limit_exceeded" } }, "required": [ "message", "code" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "plan_feature_unavailable" } }, "required": [ "message", "code" ] } ] } } } } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:accounts:read" ] } ] } }, "\/accounts\/{account}\/projects": { "get": { "operationId": "projects.index", "description": "List the DigitalOcean projects of the account by name.", "summary": "List projects", "tags": [ "Projects" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "include_deleted", "in": "query", "description": "Also return the projects that were removed from DigitalOcean.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Paginated set of `Project`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Project" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "The monthly spend is above the plan limit.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "spend_limit_exceeded" } }, "required": [ "message", "code" ] } } } } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:accounts:read" ] } ] } }, "\/accounts\/{account}\/resources": { "get": { "operationId": "resources.index", "description": "List the billable resources of the account with their cost, newest first. Returns the resources that exist unless status says otherwise.", "summary": "List resources", "tags": [ "Resources" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "type", "in": "query", "description": "Only return resources of this type: app, database, droplet, load_balancer, snapshot or volume.", "schema": { "type": [ "string", "null" ], "enum": [ "app", "volume", "droplet", "database", "snapshot", "load_balancer", null ] }, "example": "droplet" }, { "name": "project", "in": "query", "description": "Only return resources assigned to this DigitalOcean project UUID. Needs a plan with the project filter.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" }, { "name": "status", "in": "query", "description": "active for resources that exist, deleted for resources that were removed from DigitalOcean, all for both.", "schema": { "type": [ "string", "null" ], "enum": [ "active", "deleted", "all", null ], "default": "active" } }, { "name": "query", "in": "query", "description": "Search resources by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "web" } ], "responses": { "200": { "description": "Paginated set of `Resource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Resource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "The monthly spend is above the plan limit, or the plan does not include the project filter.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "spend_limit_exceeded" } }, "required": [ "message", "code" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "plan_feature_unavailable" } }, "required": [ "message", "code" ] } ] } } } } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:accounts:read" ] } ] } }, "\/accounts\/{account}\/invoices": { "get": { "operationId": "invoices.index", "description": "List the invoices of the account, newest first. The invoice of the current month is a preview with the costs up to now.", "summary": "List invoices", "tags": [ "Invoices" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Invoice`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Invoice" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:invoices:read" ] }, { "ctp": [ "billdo:invoices:read" ] }, { "ctt": [ "billdo:invoices:read" ] } ] } }, "\/accounts\/{account}\/alerts": { "get": { "operationId": "alerts.index", "description": "List the billing alerts of the account with their current value.", "summary": "List alerts", "tags": [ "Alerts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Alert" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:alerts:read" ] }, { "ctp": [ "billdo:alerts:read" ] }, { "ctt": [ "billdo:alerts:read" ] } ] }, "post": { "operationId": "alerts.create", "description": "Create a billing alert on the account. It is checked right away and then every hour.", "summary": "Create an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateAlertRequest" } } } }, "responses": { "201": { "description": "`Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Alert" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "The team has as many alerts as its plan allows.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "alert_limit_reached" } }, "required": [ "message", "code" ] } } } } }, "security": [ { "openid": [ "billdo:alerts:write" ] }, { "ctp": [ "billdo:alerts:write" ] }, { "ctt": [ "billdo:alerts:write" ] } ] } }, "\/accounts\/{account}": { "get": { "operationId": "accounts.single", "description": "Get one of the DigitalOcean accounts connected to the team. Any Bill.DO read scope grants access.", "summary": "Get an account", "tags": [ "Accounts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`Account`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Account" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "openid": [ "billdo:invoices:read" ] }, { "openid": [ "billdo:alerts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:invoices:read" ] }, { "ctp": [ "billdo:alerts:read" ] }, { "ctt": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:invoices:read" ] }, { "ctt": [ "billdo:alerts:read" ] } ] } }, "\/accounts\/{account}\/alerts\/{alert}": { "get": { "operationId": "alerts.single", "description": "Get one of the billing alerts of the account with its current value.", "summary": "Get an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "alert", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Alert" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:alerts:read" ] }, { "ctp": [ "billdo:alerts:read" ] }, { "ctt": [ "billdo:alerts:read" ] } ] }, "patch": { "operationId": "alerts.update", "description": "Change the type, limit or resource types of a billing alert. Fields left out keep their value. A changed alert is checked again right away.", "summary": "Update an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "alert", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateAlertRequest" } } } }, "responses": { "200": { "description": "`Alert`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Alert" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:alerts:write" ] }, { "ctp": [ "billdo:alerts:write" ] }, { "ctt": [ "billdo:alerts:write" ] } ] }, "delete": { "operationId": "alerts.delete", "description": "Delete a billing alert. No emails are sent for it anymore.", "summary": "Delete an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "alert", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "The alert was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:alerts:write" ] }, { "ctp": [ "billdo:alerts:write" ] }, { "ctt": [ "billdo:alerts:write" ] } ] } }, "\/accounts\/{account}\/invoices\/{invoice}\/pdf": { "get": { "operationId": "invoices.pdf", "description": "Download the PDF of an invoice, which Bill.DO retrieves from DigitalOcean on request.", "summary": "Download an invoice", "tags": [ "Invoices" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The PDF of the invoice.", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "409": { "description": "Bill.DO can no longer access the DigitalOcean account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "account_reconnect_required" } }, "required": [ "message", "code" ] } } } }, "502": { "description": "DigitalOcean did not return the PDF.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "digitalocean_unavailable" } }, "required": [ "message", "code" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } }, "security": [ { "openid": [ "billdo:invoices:read" ] }, { "ctp": [ "billdo:invoices:read" ] }, { "ctt": [ "billdo:invoices:read" ] } ] } }, "\/accounts\/{account}\/projects\/{project}": { "get": { "operationId": "projects.single", "description": "Get one of the DigitalOcean projects of the account.", "summary": "Get a project", "tags": [ "Projects" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Project`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Project" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "The monthly spend is above the plan limit.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "spend_limit_exceeded" } }, "required": [ "message", "code" ] } } } } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:accounts:read" ] } ] } }, "\/accounts\/{account}\/usage\/history": { "get": { "operationId": "accounts.usageHistory", "description": "Get the recorded spend of the account in USD per period of the range, per hour for a day, per day for up to 90 days and per month for longer ranges, split by resource type. Optionally only for a project or some resource types.", "summary": "Get the usage history", "tags": [ "Usage" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "project", "in": "query", "description": "Only count the usage of this DigitalOcean project UUID. Needs a plan with the project filter.", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "example": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" }, { "name": "resource_types[]", "in": "query", "schema": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "app", "volume", "droplet", "database", "snapshot", "load_balancer" ] }, "minItems": 1, "uniqueItems": true } }, { "name": "range", "in": "query", "description": "The time range: today and yesterday per hour; past_7_days, past_30_days, past_90_days, month and past_month per day; year, past_year and all per month.", "schema": { "anyOf": [ { "default": "past_30_days", "$ref": "#\/components\/schemas\/UsageRange" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "today", "yesterday", "past_7_days", "past_30_days", "past_90_days", "month", "past_month", "year", "past_year", "all" ], "examples": [ "past_30_days" ] }, "interval": { "type": "string", "description": "The size of each period: hour, day or month.", "enum": [ "hour", "day", "month" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "periods": { "type": "array", "description": "The periods from old to new, periods without recorded usage have zero spend.", "items": {} } }, "required": [ "range", "interval", "from", "to", "periods" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "The monthly spend is above the plan limit, or the plan does not include the project filter.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "spend_limit_exceeded" } }, "required": [ "message", "code" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "plan_feature_unavailable" } }, "required": [ "message", "code" ] } ] } } } } }, "security": [ { "openid": [ "billdo:accounts:read" ] }, { "ctp": [ "billdo:accounts:read" ] }, { "ctt": [ "billdo:accounts:read" ] } ] } } }, "components": { "securitySchemes": { "ctp": { "type": "http", "description": "Chief Tools personal access token.", "scheme": "bearer", "bearerFormat": "ctp_*" }, "openid": { "type": "openIdConnect", "openIdConnectUrl": "https:\/\/account.chief.app\/.well-known\/openid-configuration" }, "ctt": { "type": "http", "description": "Chief Tools team access token.", "scheme": "bearer", "bearerFormat": "ctt_*" } }, "schemas": { "Account": { "type": "object", "properties": { "id": { "type": "integer", "description": "Account ID.", "examples": [ 42 ] }, "name": { "type": "string", "examples": [ "Acme production" ] }, "digitalocean": { "type": "object", "properties": { "team_id": { "type": [ "string", "null" ], "description": "UUID of the DigitalOcean team the account is connected to.", "examples": [ "0f6c3a6e-6f3e-4d6c-9c0b-1f2e3d4c5b6a" ] }, "team_name": { "type": [ "string", "null" ], "examples": [ "Acme" ] }, "url": { "type": "string", "description": "Link to the DigitalOcean control panel of the team." } }, "required": [ "team_id", "team_name", "url" ] }, "connected": { "type": "boolean", "description": "Whether Bill.DO can access the DigitalOcean account, false once it needs to be reconnected in the Bill.DO dashboard." }, "imported_at": { "type": [ "string", "null" ], "description": "When the first full import of the account finished, null while it is importing." }, "invoiced_up_to": { "type": [ "string", "null" ], "description": "The end of the last invoice period that was imported." }, "stats": { "type": [ "object", "null" ], "description": "Spend in USD as last calculated by Bill.DO, about every hour. Null while spending reports are not available on the team's plan, or before the first calculation.\nUse the usage endpoint for figures calculated on request and per resource type or project.", "properties": { "hourly": { "type": "number", "description": "Current spend per hour." }, "month_to_date": { "type": "number", "description": "Spend so far this month." }, "month_predicted": { "type": "number", "description": "Predicted spend for the whole of this month." }, "next_month_predicted": { "type": "number", "description": "Predicted spend for next month when the current resources keep running." } }, "required": [ "hourly", "month_to_date", "month_predicted", "next_month_predicted" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "digitalocean", "connected", "imported_at", "invoiced_up_to", "stats", "created_at" ], "title": "Account" }, "Alert": { "type": "object", "properties": { "id": { "type": "integer", "description": "Alert ID.", "examples": [ 17 ] }, "account_id": { "type": "integer", "description": "ID of the account the alert watches.", "examples": [ 42 ] }, "type": { "type": "string", "description": "What the alert compares to its limit: hourly (current spend per hour), daily_actual (spend so far today), daily_predicted (predicted spend today), monthly_actual (spend so far this month) or monthly_predicted (predicted spend this month).", "examples": [ "monthly_predicted" ] }, "type_name": { "type": "string", "examples": [ "Monthly Prediction" ] }, "limit": { "type": "number", "description": "The limit in USD, the alert triggers once the current value exceeds it.", "examples": [ 250 ] }, "resources": { "type": "array", "description": "The resource types whose spend counts towards the alert.", "examples": [ [ "droplet", "database" ] ], "items": { "type": "string" } }, "current_value": { "type": "number", "description": "The current value in USD of what the alert watches." }, "percentage": { "type": "number", "description": "The current value as a percentage of the limit." }, "is_alarming": { "type": "boolean", "description": "Whether the alert is triggered: the current value exceeded the limit and did not drop below it since. Recipients are emailed when this changes." }, "last_checked_at": { "type": [ "string", "null" ] }, "last_state_change_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "account_id", "type", "type_name", "limit", "resources", "current_value", "percentage", "is_alarming", "last_checked_at", "last_state_change_at", "created_at" ], "title": "Alert" }, "CreateAlertRequest": { "type": "object", "properties": { "type": { "type": "string", "description": "What the alert compares to its limit: hourly (current spend per hour), daily_actual (spend so far today), daily_predicted (predicted spend today), monthly_actual (spend so far this month) or monthly_predicted (predicted spend this month).", "enum": [ "hourly", "daily_actual", "daily_predicted", "monthly_actual", "monthly_predicted" ], "examples": [ "monthly_predicted" ] }, "limit": { "type": "number", "description": "The limit in USD, the alert triggers once the current value exceeds it.", "examples": [ 250 ], "minimum": 0.0001, "maximum": 100000000 }, "resources": { "type": "array", "description": "The resource types whose spend counts towards the alert: app, database, droplet, load_balancer, snapshot or volume.", "examples": [ [ "droplet", "database" ] ], "items": { "type": "string", "enum": [ "app", "volume", "droplet", "database", "snapshot", "load_balancer" ] }, "minItems": 1, "uniqueItems": true } }, "required": [ "type", "limit", "resources" ], "title": "CreateAlertRequest" }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "DigitalOcean invoice UUID.", "examples": [ "8a4bc9a2-2f4e-4c1b-9d7e-3b2a1c0d9e8f" ] }, "period": { "type": "string", "description": "The month the invoice is for.", "examples": [ "2026-09" ] }, "amount": { "type": "number", "description": "Invoiced amount in USD.", "examples": [ 123.45 ] }, "preview": { "type": "boolean", "description": "Whether this is a preview of the current month with the costs up to now instead of the final invoice." }, "url": { "type": "string", "description": "Link to the invoice in the DigitalOcean control panel." } }, "required": [ "id", "period", "amount", "preview", "url" ], "title": "Invoice" }, "Project": { "type": "object", "properties": { "id": { "type": "string", "description": "DigitalOcean project UUID.", "examples": [ "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" ] }, "name": { "type": "string", "examples": [ "Webshop" ] }, "description": { "type": "string" }, "purpose": { "type": "string", "examples": [ "Website or blog" ] }, "environment": { "type": [ "string", "null" ], "description": "Production, Staging or Development, null when not set.", "enum": [ "Production", "Staging", "Development", null ] }, "is_default": { "type": "boolean", "description": "Whether this is the default project of the DigitalOcean team, which holds the resources not assigned to another project." }, "url": { "type": "string", "description": "Link to the project in the DigitalOcean control panel." }, "stats": { "type": [ "object", "null" ], "description": "Spend in USD of the project as last calculated by Bill.DO, about every hour. Null while the team's plan does not include the project filter, or before the first calculation.", "properties": { "hourly": { "type": "number", "description": "Current spend per hour." }, "month_to_date": { "type": "number", "description": "Spend so far this month." }, "month_predicted": { "type": "number", "description": "Predicted spend for the whole of this month." }, "next_month_predicted": { "type": "number", "description": "Predicted spend for next month when the current resources keep running." } }, "required": [ "hourly", "month_to_date", "month_predicted", "next_month_predicted" ] }, "created_at": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ], "description": "When Bill.DO noticed the project was removed from DigitalOcean, null while it exists." } }, "required": [ "id", "name", "description", "purpose", "environment", "is_default", "url", "stats", "created_at", "deleted_at" ], "title": "Project" }, "Resource": { "type": "object", "properties": { "type": { "type": "string", "description": "app, database, droplet, load_balancer, snapshot or volume.", "examples": [ "droplet" ] }, "id": { "type": "string", "description": "DigitalOcean ID of the resource, unique within its type.", "examples": [ "312409876" ] }, "name": { "type": "string", "examples": [ "web-1" ] }, "region": { "type": "string", "description": "DigitalOcean region slug, null for resources without a region.", "examples": [ "ams3" ] }, "project_id": { "type": [ "string", "null" ], "description": "UUID of the DigitalOcean project the resource is assigned to.", "examples": [ "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "cost": { "type": "object", "description": "The cost in USD, null when Bill.DO has no price for the size of the resource.", "properties": { "hourly": { "type": [ "number", "null" ], "description": "Cost per hour." }, "monthly": { "type": [ "number", "null" ], "description": "Cost per month of running the whole month." }, "month_predicted": { "type": [ "number", "null" ], "description": "Predicted cost for this month, 0 for removed resources." } }, "required": [ "hourly", "monthly", "month_predicted" ] }, "details": { "type": "object", "description": "The specifications of the resource, which depend on its type.", "additionalProperties": {} }, "created_at": { "type": [ "string", "null" ], "description": "When the resource was created at DigitalOcean." }, "deleted_at": { "type": [ "string", "null" ], "description": "When Bill.DO noticed the resource was removed from DigitalOcean, null while it exists." } }, "required": [ "type", "id", "name", "region", "project_id", "tags", "cost", "details", "created_at", "deleted_at" ], "title": "Resource" }, "Team": { "type": "object", "properties": { "slug": { "type": "string", "description": "Team slug, the value of the X-Chief-Team header.", "examples": [ "acme" ] }, "name": { "type": "string", "examples": [ "Acme" ] }, "timezone": { "type": [ "string", "null" ], "description": "Timezone of the team.", "examples": [ "Europe\/Amsterdam" ] }, "limits": { "type": "object", "description": "The plan limits of the team. A null limit is unlimited.", "properties": { "alerts": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "Alerts the team's accounts may have together, null for unlimited." }, "usage": { "type": "integer" } }, "required": [ "limit", "usage" ] }, "monthly_spend": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "Predicted monthly spend in USD of all the team's accounts up to which spending reports are available, null for unlimited." }, "usage": { "type": "integer", "description": "Predicted monthly spend in USD of all the team's accounts, rounded down." } }, "required": [ "limit", "usage" ] } }, "required": [ "alerts", "monthly_spend" ] }, "project_filter": { "type": "boolean", "description": "Whether the plan includes usage per project and filtering usage, history and resources on a project." }, "spending_reports": { "type": "boolean", "description": "Whether spending reports (usage, history, projects and resources) are available, false while the monthly spend is above the plan limit." }, "can_create_alerts": { "type": "boolean", "description": "Whether another alert can be created within the plan limit." } }, "required": [ "slug", "name", "timezone", "limits", "project_filter", "spending_reports", "can_create_alerts" ], "title": "Team" }, "UpdateAlertRequest": { "type": "object", "description": "The fields of an alert to change, fields left out keep their value.", "properties": { "type": { "type": "string", "description": "What the alert compares to its limit: hourly (current spend per hour), daily_actual (spend so far today), daily_predicted (predicted spend today), monthly_actual (spend so far this month) or monthly_predicted (predicted spend this month).", "enum": [ "hourly", "daily_actual", "daily_predicted", "monthly_actual", "monthly_predicted" ], "examples": [ "monthly_predicted" ] }, "limit": { "type": "number", "description": "The limit in USD, the alert triggers once the current value exceeds it.", "examples": [ 250 ], "minimum": 0.0001, "maximum": 100000000 }, "resources": { "type": "array", "description": "The resource types whose spend counts towards the alert: app, database, droplet, load_balancer, snapshot or volume.", "examples": [ [ "droplet", "database" ] ], "items": { "type": "string", "enum": [ "app", "volume", "droplet", "database", "snapshot", "load_balancer" ] }, "minItems": 1, "uniqueItems": true } }, "title": "UpdateAlertRequest" }, "UsageRange": { "type": "string", "description": "The time ranges usage history can be requested for, matching the ranges of the dashboard graph.\n", "enum": [ "today", "yesterday", "past_7_days", "past_30_days", "past_90_days", "month", "past_month", "year", "past_year", "all" ], "title": "UsageRange" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }