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: table: value: _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: - _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 inputRow: value: _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 type: row tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: Mike age: 30 relationship: - ro_ta_... row: value: _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4 type: row tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70 name: Mike age: 30 relationship: - primaryDisplay: Joe _id: ro_ta_... search: 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 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: row: description: The row to be created/updated, based on the table schema. type: object additionalProperties: oneOf: - type: string - type: object - type: integer - type: array - type: boolean table: description: The table to be created/updated. type: object 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: 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. query: type: object properties: {} user: type: object properties: {} application: type: object properties: {} security: - ApiKeyAuth: [] paths: /applications/search: post: summary: Search for an application based on its app name. tags: - applications parameters: - $ref: "#/components/parameters/appId" responses: "200": description: Returns the applications that were found based on the search parameters. content: application/json: schema: type: array items: $ref: "#/components/schemas/application" /applications: post: summary: Create a new application. tags: - applications parameters: - $ref: "#/components/parameters/appId" responses: "200": description: Returns the created application. content: application/json: schema: type: object "/applications/{appId}": put: summary: Update an existing application by its ID. tags: - applications parameters: - $ref: "#/components/parameters/appIdUrl" responses: "200": description: Returns the updated application. content: application/json: schema: type: object 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: type: object /queries/search: post: summary: Search for a query based on its name. tags: - queries parameters: - $ref: "#/components/parameters/appId" responses: "200": description: Returns the queries found based on the search parameters. content: application/json: schema: type: array items: $ref: "#/components/schemas/query" "/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: array items: type: object "/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 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 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/search" "/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: type: object 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: type: object 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: type: object examples: row: $ref: "#/components/examples/row" get: summary: Get 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 retrieved row. content: application/json: schema: type: object examples: row: $ref: "#/components/examples/row" /tables/search: post: summary: Search internal and external tables based on their name. tags: - tables parameters: - $ref: "#/components/parameters/appId" requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the table, this is a case insensitive search using the provided name as a starts with search. responses: "200": description: Returns the found tables, based on the search parameters. content: application/json: schema: type: array items: type: object examples: tables: $ref: "#/components/examples/tables" /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: type: object examples: table: $ref: "#/components/examples/table" /tables/:tableId: put: summary: Update the specified table. This can be for internal or external tables. 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: type: object examples: table: $ref: "#/components/examples/row" "/tables/{tableId}": 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: type: object examples: table: $ref: "#/components/examples/table" /users/search: post: summary: Search for a user based on their email/username. tags: - users parameters: - $ref: "#/components/parameters/appId" responses: "200": description: Returns the found users based on search parameters. content: application/json: schema: type: array items: $ref: "#/components/schemas/user" /users: post: summary: Create a new user in the Budibase portal. tags: - users parameters: - $ref: "#/components/parameters/appId" responses: "200": description: Returns the created user. content: application/json: schema: type: object "/users/{userId}": put: summary: Update an existing user by their ID. tags: - users parameters: - $ref: "#/components/parameters/userId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the updated user. content: application/json: schema: type: object delete: summary: Delete an existing user by their ID. tags: - users parameters: - $ref: "#/components/parameters/userId" - $ref: "#/components/parameters/appId" responses: "200": description: Returns the deleted user. content: application/json: schema: type: object tags: []