openapi: 3.0.0 info: title: Budibase API description: The public API for Budibase apps and its services. version: 1.0.0 servers: - url: http://budibase.app/api/public/v1 description: Budibase Cloud API - url: "{protocol}://{hostname}:10000/api/public/v1" description: Budibase self hosted API components: parameters: tableId: in: path name: tableId required: true description: The ID of the table which this request is targeting. schema: type: string rowId: in: path name: rowId required: true description: The ID of the row which this request is targeting. schema: type: string appId: in: header name: x-budibase-app-id required: true description: The ID of the app which this request is targeting. schema: type: string appIdUrl: in: path name: appId required: true description: The ID of the app which this request is targeting. schema: type: string queryId: in: path name: queryId required: true description: The ID of the query which this request is targeting. schema: type: string userId: in: path name: userId required: true description: The ID of the user which this request is targeting. schema: type: string examples: application: value: application: _id: app_metadata appId: app_dev_957b12f943d348faa61db7e18e088d0f version: 1.0.58-alpha.0 name: App name url: /app-url tenantId: default updatedAt: 2022-02-22T13:00:54.035Z createdAt: 2022-02-11T18:02:26.961Z status: development lockedBy: _id: us_693a73206518477283a8d5ae31103252 email: test@test.com roles: app_957b12f943d348faa61db7e18e088d0f: BASIC builder: global: false admin: global: true tenantId: default status: active budibaseAccess: true csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4 userId: us_693a73206518477283a8d5ae31103252 roleId: ADMIN role: _id: ADMIN name: Admin permissionId: admin inherits: POWER applications: value: applications: - _id: app_metadata appId: app_dev_957b12f943d348faa61db7e18e088d0f version: 1.0.58-alpha.0 name: App name url: /app-url tenantId: default updatedAt: 2022-02-22T13:00:54.035Z createdAt: 2022-02-11T18:02:26.961Z status: development lockedBy: _id: us_693a73206518477283a8d5ae31103252 email: test@test.com roles: app_957b12f943d348faa61db7e18e088d0f: BASIC builder: global: false admin: global: true tenantId: default status: active budibaseAccess: true csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4 userId: us_693a73206518477283a8d5ae31103252 roleId: ADMIN role: _id: ADMIN name: Admin permissionId: admin inherits: POWER inputRow: value: _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 type: row tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: Mike age: 30 relationship: - ro_ta_... row: value: row: _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 type: row tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: Mike age: 30 relationship: - primaryDisplay: Joe _id: ro_ta_... enrichedRow: value: row: _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 name: eg tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 type: row relationship: - _id: ro_ta_users_us_8f3d717147d74d759d8cef5b6712062f name: Joe tableId: ta_users internal: - _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 primaryDisplay: eg rows: value: rows: - _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 type: row tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: Mike age: 30 relationship: - primaryDisplay: Joe _id: ro_ta_... hasNextPage: true bookmark: 10 table: value: table: _id: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: People schema: name: type: string name: name age: type: number name: age relationship: type: link name: relationship tableId: ta_... fieldName: relatedColumn relationshipType: many-to-many tables: value: tables: - _id: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: People schema: name: type: string name: name age: type: number name: age relationship: type: link name: relationship tableId: ta_... fieldName: relatedColumn relationshipType: many-to-many query: value: query: _id: query_datasource_plus_4d8be0c506b9465daf4bf84d890fdab6_454854487c574d45bc4029b1e153219e datasourceId: datasource_plus_4d8be0c506b9465daf4bf84d890fdab6 parameters: [] fields: sql: select * from persons queryVerb: read name: Help schema: personid: name: personid type: string lastname: name: lastname type: string firstname: name: firstname type: string address: name: address type: string city: name: city type: string transformer: return data readable: true queries: value: queries: - _id: query_datasource_plus_4d8be0c506b9465daf4bf84d890fdab6_454854487c574d45bc4029b1e153219e datasourceId: datasource_plus_4d8be0c506b9465daf4bf84d890fdab6 parameters: [] fields: sql: select * from persons queryVerb: read name: Help schema: personid: name: personid type: string lastname: name: lastname type: string firstname: name: firstname type: string address: name: address type: string city: name: city type: string transformer: return data readable: true restResponse: value: data: - value: pagination: cursor: "2" raw: headers: content-type: text/html; charset=ISO-8859-1 sqlResponse: value: data: - personid: 1 lastname: Hughes firstname: Mike address: 123 Fake Street city: Belfast - personid: 2 lastname: Smith firstname: John address: 64 Updown Road city: Dublin user: value: user: _id: us_693a73206518477283a8d5ae31103252 email: test@test.com roles: app_957b12f943d348faa61db7e18e088d0f: BASIC builder: global: false admin: global: true tenantId: default status: active budibaseAccess: true csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4 userId: us_693a73206518477283a8d5ae31103252 roleId: ADMIN role: _id: ADMIN name: Admin permissionId: admin inherits: POWER users: value: users: - _id: us_693a73206518477283a8d5ae31103252 email: test@test.com roles: app_957b12f943d348faa61db7e18e088d0f: BASIC builder: global: false admin: global: true tenantId: default status: active budibaseAccess: true csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4 userId: us_693a73206518477283a8d5ae31103252 roleId: ADMIN role: _id: ADMIN name: Admin permissionId: admin inherits: POWER securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-budibase-api-key description: Your individual API key, this will provide access based on the configured RBAC settings of your user. schemas: application: type: object properties: name: description: The name of the app. type: string url: description: The URL by which the app is accessed, this must be URL encoded. type: string required: - name - url applicationOutput: type: object properties: application: type: object properties: name: description: The name of the app. type: string url: description: The URL by which the app is accessed, this must be URL encoded. type: string status: description: The status of the app, stating it if is the development or published version. type: string enum: - development - published createdAt: description: States when the app was created, will be constant. Stored in ISO format. type: string updatedAt: description: States the last time the app was updated - stored in ISO format. type: string version: description: States the version of the Budibase client this app is currently based on. type: string tenantId: description: In a multi-tenant environment this will state the tenant this app is within. type: string lockedBy: description: The user this app is currently being built by. type: object appId: description: The ID of the app. type: string required: - name - url - status - createdAt - updatedAt - version - appId required: - application row: description: The row to be created/updated, based on the table schema. type: object properties: _id: description: The ID of the row. type: string tableId: description: The ID of the table this row comes from. type: string additionalProperties: oneOf: - type: string - type: object - type: integer - type: array - type: boolean rowOutput: type: object properties: row: description: The row to be created/updated, based on the table schema. type: object properties: _id: description: The ID of the row. type: string tableId: description: The ID of the table this row comes from. type: string additionalProperties: oneOf: - type: string - type: object - type: integer - type: array - type: boolean required: - row table: description: The table to be created/updated. type: object required: - name - schema properties: name: description: The name of the table type: string primaryDisplay: type: string description: The name of the column which should be used in relationship tags when relating to this table. schema: type: object additionalProperties: oneOf: - type: object properties: type: type: string enum: - link description: A relationship column. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. fieldName: type: string description: The name of the column which a relationship column is related to in another table. tableId: type: string description: The ID of the table which a relationship column is related to. relationshipType: type: string enum: - one-to-many - many-to-one - many-to-many description: Defines the type of relationship that this column will be used for. through: type: string description: When using a SQL table that contains many to many relationships this defines the table the relationships are linked through. foreignKey: type: string description: When using a SQL table that contains a one to many relationship this defines the foreign key. throughFrom: type: string description: When using a SQL table that utilises a through table, this defines the primary key in the through table for this table. throughTo: type: string description: When using a SQL table that utilises a through table, this defines the primary key in the through table for the related table. - type: object properties: type: type: string enum: - formula description: A formula column. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. formula: type: string description: Defines a Handlebars or JavaScript formula to use, note that Javascript formulas are expected to be provided in the base64 format. formulaType: type: string enum: - static - dynamic description: Defines whether this is a static or dynamic formula. - type: object properties: type: type: string enum: - string - longform - options - number - boolean - array - datetime - attachment - link - formula - auto - json - internal description: Defines the type of the column, most explain themselves, a link column is a relationship. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. tableOutput: type: object properties: table: description: The table to be created/updated. type: object required: - name - schema properties: name: description: The name of the table type: string primaryDisplay: type: string description: The name of the column which should be used in relationship tags when relating to this table. schema: type: object additionalProperties: oneOf: - type: object properties: type: type: string enum: - link description: A relationship column. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. fieldName: type: string description: The name of the column which a relationship column is related to in another table. tableId: type: string description: The ID of the table which a relationship column is related to. relationshipType: type: string enum: - one-to-many - many-to-one - many-to-many description: Defines the type of relationship that this column will be used for. through: type: string description: When using a SQL table that contains many to many relationships this defines the table the relationships are linked through. foreignKey: type: string description: When using a SQL table that contains a one to many relationship this defines the foreign key. throughFrom: type: string description: When using a SQL table that utilises a through table, this defines the primary key in the through table for this table. throughTo: type: string description: When using a SQL table that utilises a through table, this defines the primary key in the through table for the related table. - type: object properties: type: type: string enum: - formula description: A formula column. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. formula: type: string description: Defines a Handlebars or JavaScript formula to use, note that Javascript formulas are expected to be provided in the base64 format. formulaType: type: string enum: - static - dynamic description: Defines whether this is a static or dynamic formula. - type: object properties: type: type: string enum: - string - longform - options - number - boolean - array - datetime - attachment - link - formula - auto - json - internal description: Defines the type of the column, most explain themselves, a link column is a relationship. constraints: type: object description: A constraint can be applied to the column which will be validated against when a row is saved. properties: type: type: string enum: - string - number - object - boolean presence: type: boolean description: Defines whether the column is required or not. name: type: string description: The name of the column. autocolumn: type: boolean description: Defines whether the column is automatically generated. required: - table query: description: The query body must contain the required parameters for the query, this depends on query type, setup and bindings. type: object additionalProperties: oneOf: - type: string - type: object - type: integer - type: array - type: boolean user: type: object properties: email: description: The email address of the user, this must be unique. type: string password: description: The password of the user if using password based login - this will never be returned. This can be left out of subsequent requests (updates) and will be enriched back into the user structure. type: string status: description: The status of the user, if they are active. type: string enum: - active firstName: description: The first name of the user type: string lastName: description: The last name of the user type: string forceResetPassword: description: If set to true forces the user to reset their password on first login. type: boolean builder: description: Describes if the user is a builder user or not. type: object properties: global: description: If set to true the user will be able to build any app in the system. type: boolean admin: description: Describes if the user is an admin user or not. type: object properties: global: description: If set to true the user will be able to administrate the system. type: boolean roles: description: Contains the roles of the user per app (assuming they are not a builder user). type: object additionalProperties: type: string description: A map of app ID (production app ID, minus the _dev component) to a role ID, e.g. ADMIN. required: - email - roles userOutput: type: object properties: user: type: object properties: email: description: The email address of the user, this must be unique. type: string password: description: The password of the user if using password based login - this will never be returned. This can be left out of subsequent requests (updates) and will be enriched back into the user structure. type: string status: description: The status of the user, if they are active. type: string enum: - active firstName: description: The first name of the user type: string lastName: description: The last name of the user type: string forceResetPassword: description: If set to true forces the user to reset their password on first login. type: boolean builder: description: Describes if the user is a builder user or not. type: object properties: global: description: If set to true the user will be able to build any app in the system. type: boolean admin: description: Describes if the user is an admin user or not. type: object properties: global: description: If set to true the user will be able to administrate the system. type: boolean roles: description: Contains the roles of the user per app (assuming they are not a builder user). type: object additionalProperties: type: string description: A map of app ID (production app ID, minus the _dev component) to a role ID, e.g. ADMIN. required: - email - roles required: - user nameSearch: type: object properties: name: type: string description: The name to be used when searching - this will be used in a case insensitive starts with match. required: - name security: - ApiKeyAuth: [] paths: /applications: post: summary: Create a new application. tags: - applications parameters: - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/application" responses: "200": description: Returns the created application. content: application/json: schema: $ref: "#/components/schemas/applicationOutput" examples: application: $ref: "#/components/examples/application" "/applications/{appId}": put: summary: Update an existing application by its ID. tags: - applications parameters: - $ref: "#/components/parameters/appIdUrl" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/application" responses: "200": description: Returns the updated application. content: application/json: schema: $ref: "#/components/schemas/applicationOutput" examples: application: $ref: "#/components/examples/application" delete: summary: Delete an existing application by its ID. tags: - applications parameters: - $ref: "#/components/parameters/appIdUrl" responses: "200": description: Returns the deleted application. content: application/json: schema: $ref: "#/components/schemas/applicationOutput" examples: application: $ref: "#/components/examples/application" get: summary: Retrieve a single application by its ID. tags: - applications parameters: - $ref: "#/components/parameters/appIdUrl" responses: "200": description: Returns the retrieved application. content: application/json: schema: $ref: "#/components/schemas/applicationOutput" examples: application: $ref: "#/components/examples/application" /applications/search: post: summary: Search for an application based on its app name. tags: - applications parameters: - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/nameSearch" responses: "200": description: Returns the applications that were found based on the search parameters. content: application/json: schema: type: object required: - applications properties: applications: type: array items: $ref: "#/components/schemas/application" examples: applications: $ref: "#/components/examples/applications" "/queries/{queryId}": post: summary: Execute a query and retrieve its response. tags: - queries parameters: - $ref: "#/components/parameters/queryId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the result of the query execution. content: application/json: schema: type: object properties: data: type: array description: The data retrieved from the query. items: type: object description: The structure of the returned data will be an object, if it is just a string then this will be an object containing "value". pagination: type: object description: For supported query types this returns pagination information. properties: cursor: type: string description: The pagination cursor location. raw: type: string description: The raw query response. headers: type: object description: For REST queries the headers in the response will be returned here. examples: REST: $ref: "#/components/examples/restResponse" SQL: $ref: "#/components/examples/sqlResponse" /queries/search: post: summary: Search for a query based on its name. tags: - queries parameters: - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/nameSearch" responses: "200": description: Returns the queries found based on the search parameters. content: application/json: schema: type: object required: - queries properties: queries: type: array items: $ref: "#/components/schemas/query" examples: queries: $ref: "#/components/examples/queries" "/tables/{tableId}/rows": post: summary: Creates a new row within a specified table. tags: - rows parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/row" examples: row: $ref: "#/components/examples/inputRow" responses: "200": description: Returns the created row, including the ID which has been generated for it. This can be found in the Budibase portal, viewed under the developer information. content: application/json: schema: $ref: "#/components/schemas/rowOutput" examples: row: $ref: "#/components/examples/row" "/tables/{tableId}/rows/{rowId}": put: summary: Update a single row within a specified table. tags: - rows parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/rowId" - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/row" examples: row: $ref: "#/components/examples/inputRow" responses: "200": description: Returns the created row, including the ID which has been generated for it. content: application/json: schema: $ref: "#/components/schemas/rowOutput" examples: row: $ref: "#/components/examples/row" delete: summary: Delete a single row from the specified table. tags: - rows parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/rowId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the deleted row, including the ID which has been generated for it. content: application/json: schema: $ref: "#/components/schemas/rowOutput" examples: row: $ref: "#/components/examples/row" get: summary: Get a single row from the specified table. description: This gets a single row, it will be enriched with the full related rows, rather than the squashed "primaryDisplay" format returned by the search endpoint. tags: - rows parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/rowId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the retrieved row. content: application/json: schema: $ref: "#/components/schemas/rowOutput" examples: enrichedRow: $ref: "#/components/examples/enrichedRow" "/tables/{tableId}/rows/search": post: summary: Used to search for rows within a table. tags: - rows parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: object properties: string: type: object example: columnName1: value columnName2: value description: A map of field name to the string to search for, this will look for rows that have a value starting with the string value. additionalProperties: type: string description: The value to search for in the column. fuzzy: type: object description: A fuzzy search, only supported by internal tables. range: type: object description: Searches within a range, the format of this must be columnName -> [low, high]. example: columnName1: - 10 - 20 equal: type: object description: Searches for rows that have a column value that is exactly the value set. notEqual: type: object description: Searches for any row which does not contain the specified column value. empty: type: object description: Searches for rows which do not contain the specified column. The object should simply contain keys of the column names, these can map to any value. example: columnName1: "" notEmpty: type: object description: Searches for rows which have the specified column. oneOf: type: object description: Searches for rows which have a column value that is any of the specified values. The format of this must be columnName -> [value1, value2]. paginate: type: boolean description: Enables pagination, by default this is disabled. bookmark: oneOf: - type: string - type: integer description: If retrieving another page, the bookmark from the previous request must be supplied. limit: type: integer description: The maximum number of rows to return, useful when paginating, for internal tables this will be limited to 1000, for SQL tables it will be 5000. sort: type: object description: A set of parameters describing the sort behaviour of the search. properties: order: type: string enum: - ascending - descending description: The order of the sort, by default this is ascending. column: type: string description: The name of the column by which the rows will be sorted. type: type: string enum: - string - number description: Defines whether the column should be treated as a string or as numbers when sorting. responses: "200": description: The response will contain an array of rows that match the search parameters. content: application/json: schema: type: object required: - rows properties: rows: description: An array of rows, these will each contain an _id field which can be used to update or delete them. type: array items: type: object bookmark: oneOf: - type: string - type: integer description: If pagination in use, this should be provided. hasNextPage: description: If pagination in use, this will determine if there is another page to fetch. type: boolean examples: search: $ref: "#/components/examples/rows" /tables: post: summary: Create a new table. tags: - tables parameters: - $ref: "#/components/parameters/appId" requestBody: content: application/json: schema: $ref: "#/components/schemas/table" examples: table: $ref: "#/components/examples/table" responses: "200": description: Returns the created table, including the ID which has been generated for it. This can be internal or external data sources. content: application/json: schema: $ref: "#/components/schemas/tableOutput" examples: table: $ref: "#/components/examples/table" "/tables/{tableId}": put: summary: Update the specified table. tags: - tables parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/appId" requestBody: content: application/json: schema: $ref: "#/components/schemas/table" examples: table: $ref: "#/components/examples/table" responses: "200": description: Returns the updated table. content: application/json: schema: $ref: "#/components/schemas/tableOutput" examples: table: $ref: "#/components/examples/table" delete: summary: Delete a single table and all of its data. tags: - tables parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the deleted table. content: application/json: schema: $ref: "#/components/schemas/tableOutput" examples: table: $ref: "#/components/examples/table" get: summary: Gets a single table by its ID. tags: - tables parameters: - $ref: "#/components/parameters/tableId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the retrieved table. content: application/json: schema: $ref: "#/components/schemas/tableOutput" examples: table: $ref: "#/components/examples/table" /tables/search: post: summary: Search internal and external tables based on their name. tags: - tables parameters: - $ref: "#/components/parameters/appId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/nameSearch" responses: "200": description: Returns the found tables, based on the search parameters. content: application/json: schema: type: object required: - tables properties: tables: type: array items: $ref: "#/components/schemas/table" examples: tables: $ref: "#/components/examples/tables" /users: post: summary: Create a new user in the Budibase portal. tags: - users requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/user" responses: "200": description: Returns the created user. content: application/json: schema: $ref: "#/components/schemas/userOutput" examples: user: $ref: "#/components/examples/user" "/users/{userId}": put: summary: Update an existing user by their ID. tags: - users parameters: - $ref: "#/components/parameters/userId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/user" responses: "200": description: Returns the updated user. content: application/json: schema: $ref: "#/components/schemas/userOutput" examples: user: $ref: "#/components/examples/user" delete: summary: Delete an existing user by their ID. tags: - users parameters: - $ref: "#/components/parameters/userId" responses: "200": description: Returns the deleted user. content: application/json: schema: $ref: "#/components/schemas/userOutput" examples: user: $ref: "#/components/examples/user" get: summary: Retrieve a single user by their ID. tags: - users parameters: - $ref: "#/components/parameters/userId" responses: "200": description: Returns the retrieved user. content: application/json: schema: $ref: "#/components/schemas/userOutput" examples: user: $ref: "#/components/examples/user" /users/search: post: summary: Search for a user based on their email/username. tags: - users requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/nameSearch" responses: "200": description: Returns the found users based on search parameters. content: application/json: schema: type: object required: - users properties: users: type: array items: $ref: "#/components/schemas/user" examples: users: $ref: "#/components/examples/users" tags: []