> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fibery.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP tool reference (full)
> Deep reference for every Fibery MCP Server tool: parameters, value formats, examples.
This reference is for the nerds who want to know all the internals.
## Common Concepts
**Database name** — Always `"Space/Database"` format, e.g. `"SoftDev/bug"`, `"Product Management/feature"`. Names are case-sensitive.
**Field name** — Always `"Space/FieldName"` format. **The space prefix does not necessarily match the database's own space.** Fields inherited from system apps use their own prefixes: `user/name`, `assignments/assignees`, `workflow/state`, `comments/comments`, `icon/icon`. Always derive field names from `schema_detailed` output, never guess them.
**`fibery/id`** — Internal UUID for an entity (e.g., `"5766cc9a-ae80-4893-82d3-db8b78fdfa13"`). Required for updates, state changes, and document operations. Retrieved via `query`.
**`fibery/public-id`** — Human-readable string ID (e.g., `"13961"`). Used in web URLs and `get_entity_links`.
**System fields** — Auto-populated and read-only: `fibery/id`, `fibery/public-id`, `fibery/creation-date`, `fibery/modification-date`, `fibery/created-by`, `fibery/modified-by`.
**Formula fields** — Always read-only. Identified by the `formula:` comment in `schema_detailed` output.
**Typical sequence for entity work** — `schema` → `schema_detailed` → `query` (to get IDs) → write tools.
## Workspace & Schema
### `schema`
Returns the high-level structure of the workspace: all spaces and their databases, without field details.
**Parameters** — None.
**Returns** — All spaces and database names in the workspace.
**Example output (excerpt)**
```javascript theme={null}
space SoftDev {
database SoftDev/Commit
database SoftDev/Deployment
database SoftDev/Dev Task
database SoftDev/bug
}
space Product Management {
database Product Management/Insight
database Product Management/Product Area
database Product Management/feature
}
```
**Note** — Call this first before any other tool. It is the source of truth for valid database names.
### `schema_detailed`
Returns field definitions and enum values for specific databases in YAML format.
**Parameters**
| Name | Type | Required | Description |
| ------------------------- | --------- | -------- | ------------------------------------------------------------------ |
| `databases` | string\[] | Yes | Database names in `"Space/Database"` format |
| `includeRelatedDatabases` | boolean | No | Also include related databases with their fields. Default: `false` |
**Returns** — Per-database YAML with field names, types, and metadata comments: `read-only`, `formula`, `collection`, `UI title`, `default`.
**Example**
```json theme={null}
{
"databases": [
"SoftDev/bug"
],
"includeRelatedDatabases": false
}
```
**Example output (excerpt)**
```yaml theme={null}
SoftDev/bug: # Bug is an issue in a product.
fields:
fibery/id: fibery/uuid # read-only
fibery/public-id: fibery/text # read-only
fibery/creation-date: fibery/date-time # read-only; default: $now
user/name: fibery/text # UI title
user/Owner: fibery/user # default: $my-id
user/urgent: fibery/bool
user/Product Area: Product Management/Product Area
user/feature: Product Management/feature
SoftDev/Regression: fibery/bool
SoftDev/Created By AI: fibery/bool
SoftDev/Dev Task: SoftDev/Dev Task
assignments/assignees: fibery/user # collection
workflow/state: workflow/state_SoftDev/bug # default: Icebox
comments/comments: comments/comment # collection
```
**Key reading rules for this output**
* Fields marked `read-only` or `formula:` cannot be written.
* Fields marked `collection` require `add_collection_items` / `remove_collection_items` to modify.
* `workflow/state` fields require `set_state` to modify.
* `Collaboration~Documents/Document` fields require `set_document_content` or `append_document_content`.
* The field name as shown (including its space prefix) is exactly what goes in `q/select`, `update_entities`, etc.
### `get_me`
Returns information about the currently authenticated user.
**Parameters** — None.
**Returns** — `fibery/id`, `user/name`, `user/email`, `fibery/role`, `fibery/admin?`.
**Example output**
```json theme={null}
{
"fibery/admin?": true,
"user/email": "michael@fibery.io",
"fibery/role": "role/admin",
"fibery/id": "0000000",
"user/name": "Michael Dubakov"
}
```
## Querying & Searching
### `query`
Executes a Fibery Query API command against any database. Supports field selection, filtering, sorting, pagination, sub-queries, and aggregation.
**Parameters**
| Name | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `query` | object | Yes | Query definition (see below) |
| `params` | object | No | Parameter values referenced in `q/where` via `$param` syntax. Default: `\{\}` |
**`query` object fields**
| Field | Type | Required | Description |
| ------------ | ------------------- | -------- | --------------------------------------------- |
| `q/from` | string | Yes | Source database, e.g. `"SoftDev/bug"` |
| `q/select` | object \| string\[] | Yes | Fields to retrieve |
| `q/where` | array | No | Filter expression |
| `q/order-by` | array | No | Sort criteria |
| `q/limit` | number | No | Results per page. Default: `100`. Max: `1000` |
| `q/offset` | number | No | Results to skip for pagination. Default: `0` |
**Field selection — basic**
```json theme={null}
{
"Name": "user/name"
}
```
**Field selection — related entity field**
```json theme={null}
{
"OwnerName": [
"user/Owner",
"user/name"
]
}
```
**Field selection — sub-query (q/limit is required)**
```json theme={null}
{
"Assignees": {
"q/from": "assignments/assignees",
"q/select": {
"Who": "user/name"
},
"q/limit": 10
}
}
```
**Field selection — aggregation**
```json theme={null}
{
"TotalBugs": [
"q/count",
"fibery/id"
]
}
```
Available aggregate functions: `q/count`, `q/sum`, `q/avg`, `q/min`, `q/max`. `q/sum`/`q/avg`/`q/min`/`q/max` require a numeric sub-field: `["q/sum", ["Related Field", "Number Field"]]`.
**Filter operators by field type**
| Field type | Operators |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Number, Date | `=`, `!=`, `<`, `<=`, `>`, `>=`, `q/null?` |
| Text | `q/equals-ignoring-case?`, `q/not-equals-ignoring-case?`, `q/contains`, `q/not-contains`, `q/starts-with-ignoring-case?`, `q/ends-with-ignoring-case?`, `q/null-or-empty?` |
| Boolean / null check | `["=", ["q/null?", ["FieldPath"]], "$boolParam"]` |
| Reference | `q/in`, `q/not-in`, `q/count` |
| Date-range start/end | `["q/start", ["FieldPath"]]`, `["q/end", ["FieldPath"]]` |
| Location | `["q/address", ["FieldPath"]]` — parses to string, then use text operators |
**Filter combinators**
`q/and` and `q/or` take multiple filter clauses as operands:
```json theme={null}
["q/and", ["=", ["State"], "$state"], [">", ["Priority"], "$min"]]
```
**Constraint** — All filter values in `q/where` must use `$param` references. Inline literals will cause an error.
**Constraint** — `q/limit` is required in every sub-query.
**Example — bugs currently In Progress with assignees**
```json theme={null}
{
"query": {
"q/from": "SoftDev/bug",
"q/select": {
"Name": [
"user/name"
],
"Status": [
"workflow/state",
"enum/name"
],
"PublicId": [
"fibery/public-id"
],
"Urgent": [
"user/urgent"
],
"Assignees": {
"q/from": "assignments/assignees",
"q/select": {
"Who": "user/name"
},
"q/limit": 10
}
},
"q/where": [
"q/equals-ignoring-case?",
[
"workflow/state",
"enum/name"
],
"$status"
],
"q/order-by": [
[
[
"fibery/creation-date"
],
"q/desc"
]
],
"q/limit": 20
},
"params": {
"$status": "In Progress"
}
}
```
**Example output**
```json theme={null}
[
{
"Name": "Inline comment icons shift to a wrong position",
"Status": "In Progress",
"PublicId": "13959",
"Urgent": false,
"Assignees": [
{
"Who": "Nastya Karabitskaya"
}
]
}
]
```
**Example — count all bugs**
```json theme={null}
{
"query": {
"q/from": "SoftDev/bug",
"q/select": [
"q/count",
"fibery/id"
]
}
}
```
**Example — recent features with owner and planned dates**
```json theme={null}
{
"query": {
"q/from": "Product Management/feature",
"q/select": {
"Name": [
"Product Management/name"
],
"Status": [
"workflow/state",
"enum/name"
],
"Owner": [
"Product Management/owner",
"user/name"
],
"PlannedDates": [
"Product Management/planned-dates"
]
},
"q/order-by": [
[
[
"fibery/creation-date"
],
"q/desc"
]
],
"q/limit": 5
}
}
```
**Example output**
```json theme={null}
[
{
"Name": "Handle Large Datasets in Tables",
"Status": "Icebox",
"Owner": "Victor Zhuk",
"PlannedDates": null
},
{
"Name": "Migrate on history v2 routes",
"Status": "In Progress",
"Owner": "Eugene Kisel",
"PlannedDates": null
}
]
```
### `search`
Searches workspace content using BM-25 keyword matching against entity titles, descriptions, document content, and comments.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Yes | Search query string |
| `database` | string | No | Limit results to a specific database |
| `limit` | number | No | Max results. Default: `20`. Max: `100` |
| `viewType` | string | No | Filter by view type: `document`, `grid`, `list`, `board`, `timeline`, `calendar`, `map`, `feed`, `gallery`, `gantt`, `form`, `report` |
**Returns** — Matching items with `kind` (`"entity"` or `"view"`), `id`, `publicId`, `title`, `score`, `highlight`, `space`.
**Note** — Highlights use `` tags around matched terms.
**Example**
```json theme={null}
{
"query": "whiteboard",
"limit": 3
}
```
**Example output**
```json theme={null}
{
"items": [
{
"kind": "entity",
"id": "78558418-4910-44a0-a19b-3fea99c0553d",
"publicId": "3193",
"title": "Whiteboards, Whiteboards, Whiteboards!",
"score": 1256419.8,
"highlight": {
"kind": "title",
"value": "Whiteboards, ..."
},
"space": "Administrative"
}
]
}
```
### `search_guide`
Retrieves information from the Fibery User Guide via keyword search.
**Parameters**
| Name | Type | Required | Description |
| ------- | ------ | -------- | ------------------------------- |
| `query` | string | Yes | Question or topic to search for |
**Returns** — Sorted list of relevant text fragments from the official Fibery User Guide.
**Note** — Returns platform documentation only; does not search workspace content.
### `search_history`
Searches the workspace activity history for entity and schema changes.
**Parameters**
| Name | Type | Description |
| ---------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `database` | string | Filter by database name |
| `actions` | string\[] | Filter by action: `created`, `updated`, `deleted`, `collectionItemAdded`, `collectionItemRemoved`, `archived`, `restored`, `permissionsChanged` |
| `schemaChange` | string\[] | Filter by schema change: `fieldChange`, `databaseChange`, `spaceChange` |
| `entityId` | string (UUID) | Filter by `fibery/id` |
| `entityPublicId` | string | Filter by public ID (requires `database`) |
| `entityName` | string | Substring match on entity name. Minimum 3 characters |
| `entityState` | string\[] | Filter by state: `EXIST`, `DELETED`, `ARCHIVED` |
| `authorUserId` | string (UUID) | Filter by author's `fibery/id` |
| `since` | string (ISO 8601) | Start of time range. Default: 24 hours ago |
| `until` | string (ISO 8601) | End of time range. Default: now |
| `limit` | number | Max items. Default: `50`. Max: `100` |
| `sinceItem` | string | Cursor from previous result's `sinceItem` field, for pagination |
**Returns** — History events. Each event includes `id`, `date`, `action`, `url`, `database`, `entity` (with `id`, `name`, `publicId`), `author`, `fromService`, and `changes` array (each change has `field`, `fieldTitle`, `to`).
**Example — recent bugs created today**
```json theme={null}
{
"database": "SoftDev/bug",
"actions": [
"created"
],
"limit": 3
}
```
**Example output**
```json theme={null}
{
"items": [
{
"id": "124888481",
"date": "2026-03-18T15:12:18.183Z",
"action": "created",
"url": "https://the.fibery.io/SoftDev/bug/13961",
"database": "SoftDev/bug",
"databaseTitle": "Bug",
"entity": {
"id": "0000",
"name": "Links and entities in the embedded view are not clickable",
"publicId": "13961"
},
"author": {
"id": "d125f600-...",
"name": "Alex Tsayun"
},
"fromService": null,
"changes": [
{
"field": "user/name",
"fieldTitle": "Name",
"to": "Links and entities..."
},
{
"field": "user/urgent",
"fieldTitle": "Urgent",
"to": "false"
}
]
}
],
"hasNext": true,
"sinceItem": "124888481"
}
```
**Example — paginating with sinceItem**
```json theme={null}
{
"database": "SoftDev/bug",
"actions": [
"created"
],
"sinceItem": "124888481",
"limit": 50
}
```
### `query_views`
Returns saved views (boards, grids, timelines, documents, etc.) matching optional filters.
**Parameters**
| Name | Type | Description |
| ------------ | ------------- | ----------------------------------------------------------------------------- |
| `viewType` | string | Filter by view type |
| `text` | string | Search in view name or description |
| `id` | string (UUID) | Filter by `fibery/id` |
| `publicId` | string | Filter by public ID |
| `withConfig` | boolean | Include view config. Default: `true`. Set `false` when returning many results |
**Returns** — View objects: type, name, description, space, config (if requested), and content for document views.
### `fetch_view_data`
Executes a view's configured query and returns the entities it would display, with the view's own filters, fields, and sort order applied.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------ |
| `publicId` | string | Yes | Public ID of the view (from `query_views`) |
| `limit` | number | No | Max entities to return. Default: `100` |
| `offset` | number | No | Entities to skip. Default: `0` |
**Prerequisite** — Call `query_views` first to find the view's `publicId`.
**Note** — Unlike `query`, this executes the view's saved configuration rather than a custom query.
## Entities
### `create_entities`
Creates one or more entities in a database.
**Parameters**
| Name | Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------ |
| `database` | string | Yes | Full database name |
| `entities` | object\[] | Yes | Array of field-value maps. Keys in `"Space/FieldName"` format from `schema_detailed` |
**Field value formats**
| Field type | Value format |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Text | `string` |
| Number (int, decimal) | `number` |
| Boolean | `boolean` |
| Date | ISO date string: `"2026-04-01"` |
| Date-range | `\{ "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" \}` — end date is **exclusive** |
| Single-select / single-relation | UUID string of the target entity |
| Location | `\{ "longitude": number, "latitude": number, "fullAddress": string, "addressParts": \{ "place", "district", "region", "country" \} \}` |
**Constraints**
* `fibery/id` cannot be set; it is returned after creation.
* `Collaboration~Documents/Document` fields: use `set_document_content`.
* Collection fields: use `add_collection_items`.
* `workflow/state`: use `set_state`.
* Array values are never accepted; use `add_collection_items`.
**Returns** — Created entity objects including their generated `fibery/id`.
**Example — create a bug**
```json theme={null}
{
"database": "SoftDev/bug",
"entities": [
{
"user/name": "Form fields lose value on tab switch",
"user/urgent": true,
"SoftDev/Regression": false
}
]
}
```
**Example — create a feature with planned dates**
```json theme={null}
{
"database": "Product Management/feature",
"entities": [
{
"Product Management/name": "Bulk export to CSV",
"Product Management/planned-dates": {
"start": "2026-04-01",
"end": "2026-04-15"
}
}
]
}
```
### `update_entities`
Updates specified fields on existing entities. Only provided fields are changed; all other fields are left untouched.
**Parameters**
| Name | Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `entities` | object\[] | Yes | Field-value maps. Each must include `"id"` (UUID) |
**Constraints** — Same as `create_entities`: document fields, collections, and workflow state each have their own dedicated tools.
**Example — mark a bug as urgent**
```json theme={null}
{
"database": "SoftDev/bug",
"entities": [
{
"id": "5766cc9a-ae80-4893-82d3-db8b78fdfa13",
"user/urgent": true
}
]
}
```
### `delete_entities`
Permanently deletes entities by their UUIDs. This action cannot be undone.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ---------------- | -------- | --------------------------- |
| `database` | string | Yes | Full database name |
| `ids` | string\[] (UUID) | Yes | Array of `fibery/id` values |
**Prerequisite** — Use `query` to find entity IDs before deleting.
### `set_state`
Sets the `workflow/state` of a single entity.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | --------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `state` | string | Yes | State name, e.g. `"In Progress"`, `"Done"`, `"Won't Fix"` |
**Note** — Only one workflow field exists per database. Available state names come from `schema_detailed` under the `workflow/state` field's `values:` section.
**Example — move bug to Done**
```json theme={null}
{
"database": "SoftDev/bug",
"entityId": "5766cc9a-ae80-4893-82d3-db8b78fdfa13",
"state": "Done"
}
```
**Available states for `SoftDev/bug`** (from live schema): `Icebox`, `Ready for Dev`, `In Progress`, `Implemented`, `In Testing`, `Tested`, `Done`, `Won't Fix`
**Available states for `Product Management/feature`** (from live schema): `Icebox`, `Next`, `Ready for Dev`, `In Progress`, `Implemented`, `In Testing`, `Tested`, `Done`, `Abandoned`
### `get_entity_links`
Generates Fibery web links for entities by their public IDs.
**Parameters**
| Name | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `entityPublicIds` | string\[] | Yes | Array of public ID strings (e.g., `["13961", "13960"]`) |
**Note** — Public IDs are strings like `"13961"`, not UUIDs. Retrieve them via `query` by selecting `"fibery/public-id"`.
**Example**
```json theme={null}
{
"database": "SoftDev/bug",
"entityPublicIds": [
"13961",
"13960"
]
}
```
## Documents
### `get_documents_content`
Returns the Markdown content of one or more entity documents by their secrets.
**Parameters**
| Name | Type | Required | Description |
| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `secrets` | string\[] | Yes | Document secrets |
| `reducePrompt` | string | No | Summarization instruction for large documents. Default: `"Summarize this document in 2-3 paragraphs max."` |
**How to get a document secret** — Query the entity and select the document field's secret path:
```json theme={null}
{
"query": {
"q/from": "SoftDev/bug",
"q/select": {
"Name": [
"user/name"
],
"DocSecret": [
"user/Description",
"Collaboration~Documents/secret"
]
},
"q/limit": 1
}
}
```
### `set_document_content`
Replaces the full content of a `Collaboration~Documents/Document` field on an entity.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | Document field name (e.g., `"user/Description"`, `"Product Management/description"`) |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `content` | string | Yes | Full replacement content in Markdown. `""` clears the document |
**Supported Markdown extensions** — Standard Markdown plus Fibery callouts:
```md theme={null}
> [//]: # (callout;icon-type=icon;icon=info-circle;color=#199EE3)
> Callout body here
```
**Example — set a bug description**
```json theme={null}
{
"database": "SoftDev/bug",
"field": "user/Description",
"entityId": "5766cc9a-ae80-4893-82d3-db8b78fdfa13",
"content": "## Steps to Reproduce\n\n1. Open any embedded view\n2. Enter lock mode\n3. Click a link\n\n## Expected\nLink opens. **Actual:** Nothing happens."
}
```
### `append_document_content`
Appends Markdown content to the end of an existing document field. Does not replace existing content.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | -------------------------- |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | Document field name |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `content` | string | Yes | Markdown content to append |
## Collections
### `add_collection_items`
Adds items to an entity's collection field (e.g., assignees, tags, linked bugs).
**Parameters**
| Name | Type | Required | Description |
| ---------- | ---------------- | -------- | ---------------------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | Collection field name (e.g., `"assignments/assignees"`, `"user/bugs"`) |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `items` | string\[] (UUID) | Yes | `fibery/id` values to add |
**Example — assign a user to a bug**
```json theme={null}
{
"database": "SoftDev/bug",
"field": "assignments/assignees",
"entityId": "5766cc9a-ae80-4893-82d3-db8b78fdfa13",
"items": [
"1d525780-5dcb-11e8-90b6-c6e140253257"
]
}
```
### `remove_collection_items`
Removes items from an entity's collection field.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ---------------- | -------- | ---------------------------- |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | Collection field name |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `items` | string\[] (UUID) | Yes | `fibery/id` values to remove |
## Spaces
### `create_space`
Creates a new space in the workspace.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------- |
| `name` | string | Yes | Space name. Letters, numbers, and spaces only |
| `description` | string | No | Space description |
| `color` | string | No | Hex color code, e.g. `"#4CAF50"` |
**Prerequisite** — Call `schema` to check for name conflicts.
**Example**
```json theme={null}
{
"name": "Engineering",
"description": "Engineering projects and tasks",
"color": "#2978FB"
}
```
### `delete_space`
Deletes a space and all its databases. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ------ | ------ | -------- | ---------------- |
| `name` | string | Yes | Exact space name |
**Constraint** — System spaces (`fibery/user`, `fibery/file`, `comments`, `highlights`, `vacations`) cannot be deleted.
## Databases
### `create_databases`
Creates one or more databases within existing spaces.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ----------------------------- |
| `databases` | object\[] | Yes | Array of database definitions |
**Database definition**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `name` | string | Yes | `"Space/Database"` format. Space must already exist |
| `description` | string | No | Database description |
| `color` | string | No | Hex color code |
**Auto-created fields** — `fibery/id`, `fibery/public-id`, system timestamps, `\{Space\}/Name`, `\{Space\}/Description`.
**Constraint** — Names may contain only letters, numbers, and spaces. No `/`, `\`, `.`, `&`, `?`, `!`, etc.
**Example**
```json theme={null}
{
"databases": [
{
"name": "SoftDev/Sprint",
"description": "Two-week development sprints",
"color": "#673db6"
}
]
}
```
### `rename_databases`
Renames one or more databases. Changing the space prefix moves the database to a different space.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | -------------------------- |
| `databases` | object\[] | Yes | Array of rename operations |
**Rename operation**
| Name | Type | Required | Description |
| --------- | ------ | -------- | -------------------------- |
| `oldName` | string | Yes | Current full database name |
| `newName` | string | Yes | New full database name |
**Note** — Fibery automatically updates formula and relation references after rename. External API scripts using the old name will break.
### `delete_databases`
Deletes one or more databases. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ---------------------------- |
| `databases` | string\[] | Yes | Array of full database names |
## Fields
### Naming restrictions (all field types)
Field names may contain only letters, numbers, and spaces. Special characters (`/`, `\`, `.`, `&`, `,`, `?`, `!`, etc.) are not allowed in user-created names.
### `create_primitive_fields`
Creates one or more primitive (scalar) fields in databases.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | -------------------------- |
| `fields` | object\[] | Yes | Array of field definitions |
**Field definition**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | `"Space/FieldName"` — space must match the database's space |
| `fieldType` | string | Yes | See types below |
| `description` | string | No | Field description |
| `meta` | object | No | Field-type-specific metadata |
**Supported `fieldType` values**
| Type | Description | Key `meta` options |
| ---------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fibery/text` | Text | `ui/type`: `"text"`, `"email"`, `"url"`, `"phone"` |
| `fibery/int` | Integer | — |
| `fibery/decimal` | Decimal | `ui/number-format`: `"Number"`, `"Money"`, `"Percent"`; `ui/number-currency-code` (ISO 4217); `ui/number-precision`: 0–8; `ui/number-thousand-separator?`; `ui/number-unit` |
| `fibery/bool` | Checkbox | — |
| `fibery/date` | Date | — |
| `fibery/date-time` | Date and time | — |
| `fibery/date-range` | Date range | — |
| `fibery/date-time-range` | Date and time range | — |
| `fibery/location` | Location/address | — |
| `Collaboration~Documents/Document` | Rich text document | — |
**Example — add a URL field and a money field to bugs**
```json theme={null}
{
"fields": [
{
"database": "SoftDev/bug",
"name": "SoftDev/Reproduction Link",
"fieldType": "fibery/text",
"meta": {
"ui/type": "url"
}
},
{
"database": "SoftDev/bug",
"name": "SoftDev/Fix Cost",
"fieldType": "fibery/decimal",
"meta": {
"ui/number-format": "Money",
"ui/number-currency-code": "USD",
"ui/number-precision": 2
}
}
]
}
```
### `rename_fields`
Renames one or more fields.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | ----------------- |
| `fields` | object\[] | Yes | Rename operations |
**Rename operation**
| Name | Type | Required | Description |
| ---------- | ------ | -------- | --------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `oldName` | string | Yes | Current field name |
| `newName` | string | Yes | New field name (same `"Space/"` prefix, different suffix) |
### `delete_fields`
Deletes one or more fields. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | ---------------- |
| `fields` | object\[] | Yes | Field references |
**Field reference**
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------ |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | Field name in `"Space/Field"` format |
**Note** — Deleting a relation field also removes its counterpart in the related database.
### `create_relation_fields`
Creates a relation between two databases. One relation definition creates a field in both databases.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | -------------------- |
| `fields` | object\[] | Yes | Relation definitions |
**Relation definition**
| Name | Type | Required | Description |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `database` | string | Yes | Source database |
| `relationDatabase` | string | Yes | Target database |
| `name` | string | Yes | Field name in source database |
| `relationFieldName` | string | Yes | Field name in target database. Use `"user/FieldName"` prefix when target is `fibery/user` |
| `cardinality` | string | Yes | `"one-to-one"`, `"one-to-many"`, `"many-to-one"`, `"many-to-many"` |
| `description` | string | No | Field description |
**Example — link bugs to customer requests**
```json theme={null}
{
"fields": [
{
"database": "SoftDev/bug",
"relationDatabase": "Customer Success/Customer Request",
"name": "SoftDev/Customer Requests",
"relationFieldName": "Customer Success/Related Bugs",
"cardinality": "many-to-many"
}
]
}
```
### `create_single_select_fields`
Creates one or more single-select fields with predefined options.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | ----------------- |
| `fields` | object\[] | Yes | Field definitions |
**Field definition**
| Name | Type | Required | Description |
| --------------------------- | --------- | -------- | ------------------------------------------------------------------------------------ |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | Field name |
| `options` | object\[] | Yes | Options: `\{ "name": string, "color"?: string, "icon"?: string, "value"?: number \}` |
| `defaultOption` | string | No | Option name to use as default for new entities |
| `allowNumberValueForOption` | boolean | No | Enable numeric values per option. Default: `false` |
**Example — add severity field to bugs**
```json theme={null}
{
"fields": [
{
"database": "SoftDev/bug",
"name": "SoftDev/Severity",
"options": [
{
"name": "Critical",
"color": "#d40915"
},
{
"name": "High",
"color": "#fc551f"
},
{
"name": "Medium",
"color": "#fba32f"
},
{
"name": "Low",
"color": "#99a2ab"
}
],
"defaultOption": "Medium"
}
]
}
```
### `update_single_select_fields`
Updates options of existing single-select fields.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | ----------------- |
| `fields` | object\[] | Yes | Update operations |
**Update operation**
| Name | Type | Required | Description |
| --------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | Field name |
| `update` | object | Yes | Full replacement: `\{ "options": [...] \}`. Incremental: `\{ "addOptions": [...], "updateOptions": [...], "removeOptions": ["name"] \}` |
| `defaultOption` | string \| null | No | New default option. `null` clears the default |
**Note** — Incremental operations execute in order: remove → update → add. `updateOptions` matches by name; it can change `color`, `icon`, or numeric `value`, but not the option name itself.
### `create_multi_select_fields`
Creates one or more multi-select fields. Same parameters as `create_single_select_fields`, without `defaultOption`.
### `update_multi_select_fields`
Updates options of existing multi-select fields. Same parameters as `update_single_select_fields`, without `defaultOption`.
### `create_workflow_field`
Creates a workflow (state) field for tracking entities through lifecycle stages.
**Parameters**
| Name | Type | Required | Description |
| --------------- | --------- | -------- | -------------------------------------------------------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `options` | object\[] | Yes | States: `\{ "name": string, "type": "Not started" \| "Started" \| "Finished", "color"?: string \}` |
| `defaultOption` | string | Yes | State name for new entities |
**Constraint** — Only one workflow field per database. Always addressed as `"workflow/state"` in queries.
**Example — add workflow to a new database**
```json theme={null}
{
"database": "SoftDev/Sprint",
"options": [
{
"name": "Planning",
"type": "Not started",
"color": "#99a2ab"
},
{
"name": "Active",
"type": "Started",
"color": "#8ec351"
},
{
"name": "Review",
"type": "Started",
"color": "#fba32f"
},
{
"name": "Done",
"type": "Finished",
"color": "#4a4a4a"
}
],
"defaultOption": "Planning"
}
```
### `update_workflow_field`
Updates the states of an existing workflow field.
**Parameters**
| Name | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `database` | string | Yes | Full database name |
| `update` | object | Yes | Full replacement: `\{ "options": [...] \}`. Incremental: `\{ "addOptions": [...], "updateOptions": [...], "removeOptions": [...] \}` |
| `defaultOption` | string | No | New default state. Unchanged if not provided |
**Constraint** — The current default state cannot be removed until a new default is set.
### `delete_workflow_field`
Deletes the workflow field from a database. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ------------------ |
| `database` | string | Yes | Full database name |
### `create_formula_field`
Creates a calculated formula field. The formula expression is generated automatically from a natural-language description.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------- |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | Field name in `"Space/Field"` format |
| `description` | string | Yes | Natural-language description of what to calculate |
**Note** — Formula fields are always read-only. The generated formula appears in `schema_detailed` under the `formula:` comment.
**Example — count open bugs per feature**
```json theme={null}
{
"database": "Product Management/feature",
"name": "Product Management/Open Bug Count",
"description": "Count of linked bugs whose state is not Done, Tested, or Won't Fix"
}
```
### `update_formula_field`
Updates an existing formula field by regenerating its expression. The new formula must produce a compatible type with the existing field.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------- |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | Name of the existing formula field |
| `description` | string | Yes | New description for the formula |
### `create_files_fields`
Creates file attachment fields.
**Parameters**
| Name | Type | Required | Description |
| -------- | --------- | -------- | ----------------- |
| `fields` | object\[] | Yes | Field definitions |
**Field definition**
| Name | Type | Required | Description |
| -------------------- | ------- | -------- | -------------------------- |
| `database` | string | Yes | Full database name |
| `name` | string | Yes | Field name |
| `allowMultipleFiles` | boolean | Yes | Allow multiple attachments |
| `description` | string | No | Field description |
### `create_avatars_fields`
Enables avatar/profile picture attachments on entities. Creates an `"avatar/avatars"` field automatically.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
### `delete_avatars_fields`
Removes the `"avatar/avatars"` field. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
### `create_comments_fields`
Enables comments on entities. Creates a `"comments/comments"` field automatically.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
### `delete_comments_fields`
Removes the `"comments/comments"` field. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
### `create_icon_fields`
Enables emoji icons on entities. Creates an `"icon/icon"` field automatically.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
### `delete_icon_fields`
Removes the `"icon/icon"` field. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ----------- | --------- | -------- | ------------------- |
| `databases` | string\[] | Yes | Full database names |
## Views
### `create_view`
Creates a new view in the workspace.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `viewType` | string | Yes | See view types below |
| `name` | string | Yes | View name |
| `config` | object | No | View configuration (structure varies by type) |
| `content` | string | No | Markdown content (document views only) |
| `description` | string | No | Short Markdown description |
| `space` | string | No | Space to create the view in. Defaults to inferred from databases in config. Use `"Private"` for private space |
**View types**
| Type | Description |
| ---------- | ------------------------------------------------------ |
| `grid` | Spreadsheet-like table, supports hierarchical grouping |
| `list` | Simple linear list |
| `board` | Kanban board, grouped by relation or enum field |
| `timeline` | Horizontal time-bar view |
| `calendar` | Date-based calendar |
| `map` | Geographic map (requires location fields) |
| `feed` | Rich-text document feed |
| `gallery` | Card gallery with optional cover images |
| `gantt` | Hierarchical grid + timeline |
| `form` | Data-entry form for creating entities |
| `document` | Standalone rich-text document |
**`FieldUnit` format** (used in `fields` arrays inside config)
```json theme={null}
{
"field": "Space/FieldName",
"showCount": true
}
```
`"db-badge"` and `"db-badge-abbr"` are also valid `field` values.
**FilterNode `nodeType` values and their operators**
| nodeType | Operators |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `text` | `contains`, `does-not-contain`, `is`, `is-not`, `starts-with`, `ends-with`, `is-empty`, `is-not-empty` |
| `number` | `equals`, `does-not-equal`, `greater-than`, `greater-than-or-equal`, `less-than`, `less-than-or-equal`, `is-empty`, `is-not-empty` |
| `bool` | `is` |
| `date` | `is`, `is-before`, `is-after`, `is-on-or-before`, `is-on-or-after`, `is-empty`, `is-not-empty` |
| `reference` | `is-empty`, `is-not-empty` |
| `collection` | `is-empty`, `is-not-empty`, `contains-me`, `does-not-contain-me` |
| `single-select` | `is`, `is-not`, `is-any-of`, `is-none-of`, `is-empty`, `is-not-empty` |
| `workflow` | `is`, `is-not`, `is-any-of`, `is-none-of`, `is-empty`, `is-not-empty` |
| `multi-select` | `is-empty`, `is-not-empty`, `contains-any-of`, `contains-none-of`, `contains`, `does-not-contain` |
| `logical` | Combines filters with `and` / `or` |
For `single-select` and `workflow` filter values, pass arrays of option/state UUIDs. For date-range field paths, use `["q/start", "Space/Dates"]`.
**Config structure by view type**
* **grid / list** — `items[]` (ItemConfig with optional `groupBy`), `rowHeight` (`"short"`, `"medium"`, `"tall"`, `"extra-tall"`), `hideEmptyParentGroups`
* **board** — `x[]` (AxisConfig, required), `y[]` (optional), `items[]`, `cardSize` (`"compact"`, `"comfortable"`, `"spacious"`)
* **timeline / gantt** — `items[]` with `startDate`, `endDate`, `dependencyField`; `milestones[]`; `dependencyDateShiftingMode` (`"none"`, `"consume-gap"`, `"preserve-gap"`)
* **calendar** — `items[]` with `startDate`, `endDate`
* **map** — `items[]` with `location`; `style` (`"default"`, `"muted"`, `"satellite"`)
* **feed** — `items[]` with `post` (document field); `postWidth` (`"narrow"`, `"medium"`, `"full"`)
* **gallery** — `items[]` with `cover` (file field), `fillCover`; `cardSize` (`"compact"`, `"medium"`, `"full"`)
* **form** — `database`, `fields[]` with `field`, `displayName`, `required`, `description`, `hidden`, `defaultValue`
* **document** — No config needed; use `content` parameter
**AxisConfig** (board, timeline, gallery) — extends ItemConfig with `forDatabase`, `field` (relation or enum field only), `hideEmptyLanes`.
### `update_view`
Updates an existing view. Only provided fields are changed.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------------- | -------- | ----------------------------------------------------------------------- |
| `viewType` | string | Yes | View type (required for routing) |
| `id` | string (UUID) | Yes | `fibery/id` of the view (from `query_views`) |
| `name` | string | No | New name |
| `description` | string | No | New description |
| `config` | object | No | Updated configuration |
| `content` | string | No | New Markdown content (document views only) |
| `append` | boolean | No | If `true`, appends `content` instead of replacing (document views only) |
| `space` | string | No | Move the view to a different space |
### `delete_views`
Deletes views by UUID. Entity data is not affected. Restorable via Activity Log.
**Parameters**
| Name | Type | Required | Description |
| ----- | ---------------- | -------- | ----------------------- |
| `ids` | string\[] (UUID) | Yes | View `fibery/id` values |
## Files & Import
### `add_file_from_url`
Downloads a file from a URL and attaches it to an entity's file field.
**Parameters**
| Name | Type | Required | Description |
| ---------- | ------------- | -------- | --------------------------------------- |
| `database` | string | Yes | Full database name |
| `field` | string | Yes | File field name (e.g., `"Files/Files"`) |
| `entityId` | string (UUID) | Yes | `fibery/id` of the entity |
| `url` | string (URI) | Yes | HTTPS URL to download from |
| `fileName` | string | Yes | Name to assign the attached file |
**Example**
```json theme={null}
{
"database": "SoftDev/bug",
"field": "Files/Files",
"entityId": "5766cc9a-ae80-4893-82d3-db8b78fdfa13",
"url": "https://example.com/screenshots/bug-13961.png",
"fileName": "bug-13961-screenshot.png"
}
```
### `get_connectors_list`
Returns all available built-in connectors (import integrations) in the workspace.
**Parameters** — None.
**Returns** — Connectors with `name`, `id`, and supported modes (one-time import and/or continuous sync).
**Note** — When the desired source is not listed, use the `csv` connector as a fallback.
### `get_import_link`
Generates a URL to the Fibery import wizard for a given connector and target.
**Parameters**
| Name | Type | Required | Description |
| ------------- | ------- | -------- | -------------------------------------------------------------------- |
| `spaceName` | string | Yes | Target space name |
| `isSync` | boolean | Yes | `true` for continuous sync; `false` for one-time import |
| `connectorId` | string | Yes | Connector ID from `get_connectors_list` |
| `dbName` | string | No | Existing database name to import into. Omit to create a new database |
**Prerequisite** — Call `get_connectors_list` first to obtain valid `connectorId` values.
## Tool Quick Reference
| Tool | Category | Description |
| ----------------------------- | ----------- | ---------------------------------------------------------------------- |
| `get_me` | Workspace | Current user info |
| `schema` | Workspace | All spaces and databases |
| `schema_detailed` | Workspace | Fields, types, enums for specific databases |
| `query` | Querying | Flexible entity query with filtering, sorting, pagination, sub-queries |
| `search` | Querying | BM-25 keyword search across workspace content |
| `search_guide` | Querying | Search the Fibery User Guide documentation |
| `search_history` | Querying | Activity log: creates, updates, deletes, schema changes |
| `query_views` | Querying | Find saved views by type or name |
| `fetch_view_data` | Querying | Execute a saved view's query and return its entities |
| `create_entities` | Entities | Create new entities |
| `update_entities` | Entities | Update entity fields |
| `delete_entities` | Entities | Permanently delete entities |
| `set_state` | Entities | Set workflow/state |
| `get_entity_links` | Entities | Generate web links by public ID |
| `get_documents_content` | Documents | Read document field content as Markdown |
| `set_document_content` | Documents | Replace full document field content |
| `append_document_content` | Documents | Append to document field content |
| `add_collection_items` | Collections | Add items to a collection field |
| `remove_collection_items` | Collections | Remove items from a collection field |
| `create_space` | Spaces | Create a new space |
| `delete_space` | Spaces | Delete a space and all its databases |
| `create_databases` | Databases | Create new databases in a space |
| `rename_databases` | Databases | Rename or move databases between spaces |
| `delete_databases` | Databases | Delete databases |
| `create_primitive_fields` | Fields | Create scalar fields (text, number, date, bool, etc.) |
| `rename_fields` | Fields | Rename fields |
| `delete_fields` | Fields | Delete fields |
| `create_relation_fields` | Fields | Create relations between databases |
| `create_single_select_fields` | Fields | Create single-select enum fields |
| `update_single_select_fields` | Fields | Add, update, or remove single-select options |
| `create_multi_select_fields` | Fields | Create multi-select enum fields |
| `update_multi_select_fields` | Fields | Add, update, or remove multi-select options |
| `create_workflow_field` | Fields | Create a workflow/state field |
| `update_workflow_field` | Fields | Add, update, or remove workflow states |
| `delete_workflow_field` | Fields | Delete the workflow field |
| `create_formula_field` | Fields | Create a calculated formula field from a description |
| `update_formula_field` | Fields | Update a formula field's expression |
| `create_files_fields` | Fields | Create file attachment fields |
| `create_avatars_fields` | Fields | Enable avatar attachments on entities |
| `delete_avatars_fields` | Fields | Disable avatar attachments |
| `create_comments_fields` | Fields | Enable comments on entities |
| `delete_comments_fields` | Fields | Disable comments |
| `create_icon_fields` | Fields | Enable emoji icons on entities |
| `delete_icon_fields` | Fields | Disable emoji icons |
| `create_view` | Views | Create a new view |
| `update_view` | Views | Update an existing view |
| `delete_views` | Views | Delete views |
| `add_file_from_url` | Files | Download and attach a file to an entity |
| `get_connectors_list` | Import | List available import connectors |
| `get_import_link` | Import | Generate an import wizard URL |