> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-docs-next.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gryzzly

> Read and write time-tracking data in Gryzzly from Prisme.ai workflows and AI agents

The Gryzzly app provides read/write access to the [Gryzzly](https://www.gryzzly.io) time-tracking SaaS through its v1 REST-RPC API. It can be used either as a Builder app (automations call Gryzzly instructions directly) or as a remote MCP server consumed by an Knowledges agent — covering customers, projects, tasks, declarations (time entries), leave periods, discounts, purchases, users, groups and tags.

<CardGroup cols={3}>
  <Card title="Time Tracking" icon="clock">
    Declarations, leave periods and exports for payroll and invoicing
  </Card>

  <Card title="Project Structure" icon="diagram-project">
    Customers, projects, tasks and metrics with budgets and contributors
  </Card>

  <Card title="Admin & Org" icon="users">
    Users, roles, groups, groupsets, tags and tagsets
  </Card>
</CardGroup>

## Prerequisites

* A **Gryzzly** account with administrator access
* An **API key** generated in **Dashboard > Administration > API Keys**
* Base URL (default: `https://api.gryzzly.io/v1`)

***

<Tabs>
  <Tab title="Usage as App">
    ## Installation

    1. Go to **Apps** in your workspace
    2. Search for **Gryzzly** and install it
    3. Open the app instance configuration and fill in the required fields

    ## Configuration

    | Field                    | Description                                                                              |
    | ------------------------ | ---------------------------------------------------------------------------------------- |
    | **Gryzzly API Base URL** | Base URL of the Gryzzly API (default `https://api.gryzzly.io/v1`)                        |
    | **API Key**              | Gryzzly API key, stored as a workspace secret. Passed as `Authorization: Bearer <token>` |
    | **MCP Endpoint**         | Auto-populated on install — URL of the MCP endpoint for this instance                    |
    | **MCP API Key**          | Auto-populated on install — signed key used in the `mcp-api-key` header. Do not modify   |

    <Note>
      `MCP Endpoint` and `MCP API Key` are generated automatically by the `onInstall` flow and are only needed to expose this instance as an MCP server (see the next tab).
    </Note>

    ## Available Instructions

    Every instruction resolves credentials from the workspace configuration. All IDs are UUIDs returned by Gryzzly. Most list operations accept `limit` (max 1000) and `offset` for pagination.

    ### Customers

    | Instruction      | Arguments                                                     |
    | ---------------- | ------------------------------------------------------------- |
    | `listCustomers`  | `customer_ids`, `manager_ids`, `is_active`, `limit`, `offset` |
    | `getCustomer`    | `id`                                                          |
    | `createCustomer` | `name`\*, `managers`                                          |
    | `updateCustomer` | `id`*, `name`*, `is_active`, `managers`                       |
    | `deleteCustomer` | `id`\*                                                        |

    ### Projects

    | Instruction           | Arguments                                                                                                                                             |
    | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `listProjects`        | `status` (`active`/`done`/`archived`), `limit`, `offset`                                                                                              |
    | `getProject`          | `id`                                                                                                                                                  |
    | `createProject`       | `name`, `start_at`\*, `end_at`, `code`, `customer_id`, `visibility` (`public`/`private`), `is_billable`, `managers`, `contributors`, `groups`, `tags` |
    | `updateProject`       | `id`, `name`, `start_at`\*, `end_at`, `code`, `customer_id`, `status`, `visibility`, `is_billable`, `managers`, `contributors`, `groups`, `tags`      |
    | `deleteProject`       | `id`\*                                                                                                                                                |
    | `getProjectMetrics`   | `project_id`                                                                                                                                          |
    | `listProjectsMetrics` | `project_ids`\*                                                                                                                                       |
    | `exportProjects`      | `from`, `to`, `project_ids`, `type` (`csv`/`xlsx`)                                                                                                    |

    ### Tasks

    | Instruction  | Arguments                                                                                                                                                                                                                                                                     |
    | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `listTasks`  | `project_ids`, `task_ids`, `limit`, `offset`                                                                                                                                                                                                                                  |
    | `getTask`    | `id`\*                                                                                                                                                                                                                                                                        |
    | `createTask` | `name`*, `project_id`*, `start_at`\*, `end_at`, `parent_id`, `is_container`, `budget_type` (`none`/`detailed`/`global`/`time`), `budget_amount`, `planned_duration`, `estimated_duration`, `hourly_rate`, `hourly_rate_mode` (`task`/`group`/`contributor`), `groups`, `tags` |
    | `updateTask` | `id`\*, `name`, `start_at`, `end_at`, `completed_at`, `budget_amount`, `planned_duration`, `hourly_rate`, `hourly_rate_mode`, `groups`, `tags`                                                                                                                                |
    | `deleteTask` | `id`\*                                                                                                                                                                                                                                                                        |

    ### Declarations (Time Entries)

    | Instruction            | Arguments                                                             |
    | ---------------------- | --------------------------------------------------------------------- |
    | `listDeclarations`     | `task_ids`*, `user_ids`*, `from`, `to`, `limit`, `offset`             |
    | `createDeclaration`    | `date`*, `duration`* (seconds), `task_id`*, `user_id`*, `description` |
    | `updateDeclaration`    | `id`*, `date`*, `duration`*, `task_id`*, `description`                |
    | `deleteDeclaration`    | `id`\*                                                                |
    | `exportTimesAndLeaves` | `from`, `to`, `type` (`0`/`1`)                                        |

    ### Leave Periods

    | Instruction          | Arguments                                                                                                         |
    | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
    | `listLeavesPeriods`  | `user_ids`, `from`, `to`, `limit`, `offset`                                                                       |
    | `getLeavesPeriod`    | `id`\*                                                                                                            |
    | `createLeavesPeriod` | `user_id`, `start_at`, `end_at`, `start_type` (`full`/`am`/`pm`), `end_type`, `description`, `delete_declaration` |
    | `updateLeavesPeriod` | `id`, `start_at`, `end_at`, `start_type`, `end_type`, `description`, `delete_declaration`                         |
    | `deleteLeavesPeriod` | `id`                                                                                                              |

    ### Discounts

    | Instruction      | Arguments                                     |
    | ---------------- | --------------------------------------------- |
    | `listDiscounts`  | `project_ids`, `task_ids`, `limit`, `offset`  |
    | `getDiscount`    | `id`\*                                        |
    | `createDiscount` | `name`\*, `amount`, `project_id` or `task_id` |
    | `updateDiscount` | `id`, `name`, `amount`                        |
    | `deleteDiscount` | `id`\*                                        |

    ### Purchases

    | Instruction      | Arguments                                                                                                                  |
    | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `listPurchases`  | `project_ids`, `task_ids`, `limit`, `offset`                                                                               |
    | `getPurchase`    | `id`\*                                                                                                                     |
    | `createPurchase` | `name`, `project_id` or `task_id`, `billed_at`, `billed_price`, `paid_at`, `paid_price`, `billing_policy` (`add`/`ignore`) |
    | `updatePurchase` | `id`\*, `name`, `billed_at`, `billed_price`, `paid_at`, `paid_price`, `billing_policy`                                     |
    | `deletePurchase` | `id`\*                                                                                                                     |

    ### Users

    | Instruction  | Arguments                                                                                |
    | ------------ | ---------------------------------------------------------------------------------------- |
    | `listUsers`  | `limit`, `offset`                                                                        |
    | `getUser`    | `id`\*                                                                                   |
    | `inviteUser` | `email`, `role` (`contributor`/`collaborator`/`manager`/`director`/`admin`), `group_ids` |

    ### Groups & Groupsets

    | Instruction     | Arguments                                      |
    | --------------- | ---------------------------------------------- |
    | `listGroups`    | `group_ids`, `groupset_ids`, `limit`, `offset` |
    | `getGroup`      | `id`\*                                         |
    | `listGroupsets` | `groupset_ids`, `limit`, `offset`              |
    | `getGroupset`   | `id`                                           |

    ### Tags & Tagsets

    | Instruction   | Arguments                                  |
    | ------------- | ------------------------------------------ |
    | `listTags`    | `tag_ids`, `tagset_ids`, `limit`, `offset` |
    | `getTag`      | `id`\*                                     |
    | `listTagsets` | `tagset_ids`, `limit`, `offset`            |
    | `getTagset`   | `id`                                       |

    <Note>
      Arguments flagged with `*` are required.
    </Note>

    ## DSUL Examples

    ### Log a Time Declaration

    ```yaml theme={null}
    - Gryzzly.createDeclaration:
        user_id: '{{user_id}}'
        task_id: '{{task_id}}'
        date: '{{run.date}}'
        duration: 7200
        description: Implementation review
        output: declaration
    ```

    ### Create a Project With a Task

    ```yaml theme={null}
    - Gryzzly.createProject:
        name: Website Revamp
        start_at: 2026-01-06
        customer_id: '{{customer_id}}'
        visibility: private
        is_billable: true
        managers:
          - '{{manager_user_id}}'
        output: project
    - Gryzzly.createTask:
        project_id: '{{project.id}}'
        name: Design System
        start_at: 2026-01-06
        budget_type: time
        planned_duration: 80
        output: task
    ```

    ### Export Time and Leaves for Payroll

    ```yaml theme={null}
    - Gryzzly.exportTimesAndLeaves:
        from: 2026-03-01
        to: 2026-03-31
        type: 1
        output: export
    ```

    ### Invite a Contributor

    ```yaml theme={null}
    - Gryzzly.inviteUser:
        email: new.hire@example.com
        role: contributor
        group_ids:
          - '{{group_id}}'
        output: invitation
    ```
  </Tab>

  <Tab title="Usage as MCP">
    The Gryzzly app ships with a built-in MCP server. Each app instance gets its own signed `mcp-api-key` that encodes the workspace ID and a credentials lookup URL — the Gryzzly API key itself is never passed through headers and is resolved server-side from the app configuration.

    ## Legacy MCP Install (Advanced > Tools)

    Use this flow to plug the Gryzzly MCP into an Knowledges agent that does not yet support the native MCP picker.

    <Steps>
      <Step title="Install the Gryzzly app">
        Install and configure the app in the same workspace as your agent (see the *Usage as App* tab). Once configured, `mcpEndpoint` and `mcpApiKey` are auto-populated.
      </Step>

      <Step title="Copy the MCP credentials">
        Open the app instance config and copy the values of **MCP Endpoint** and **MCP API Key**.
      </Step>

      <Step title="Open your Knowledges project">
        Navigate to **Advanced > Tools**.
      </Step>

      <Step title="Add an MCP tool">
        Click **Add** and select the **MCP** tab.
      </Step>

      <Step title="Fill in the endpoint">
        Paste the **MCP Endpoint** URL copied from the app instance.
      </Step>

      <Step title="Add the auth header">
        In the **Headers** field, add the signed API key:

        ```json theme={null}
        {
          "mcp-api-key": "your-mcp-api-key"
        }
        ```
      </Step>

      <Step title="Save">
        The agent can now list and call Gryzzly tools through the MCP endpoint.
      </Step>
    </Steps>

    <Note>
      The signed `mcp-api-key` encodes the workspace ID and the `getConfig` webhook URL. The MCP server validates the signature using the central app secret and transparently fetches the Gryzzly API key and base URL from the installed app. Credentials are cached per tenant for 10 minutes.
    </Note>

    ## Output Formats

    Every tool accepts an `outputFormat` parameter that controls the MCP response shape:

    * **`verbose`** (default) — human-readable text for LLM consumption
    * **`structured`** — machine-readable JSON in `structuredContent`
    * **`both`** — both text and structured content

    ## Available Tools

    ### Customers

    | Tool             | Description       |
    | ---------------- | ----------------- |
    | `listCustomers`  | List customers    |
    | `getCustomer`    | Get a customer    |
    | `createCustomer` | Create a customer |
    | `updateCustomer` | Update a customer |
    | `deleteCustomer` | Delete a customer |

    ### Projects

    | Tool                  | Description                                                    |
    | --------------------- | -------------------------------------------------------------- |
    | `listProjects`        | List projects (filter by `status`: `active`/`done`/`archived`) |
    | `getProject`          | Get a project                                                  |
    | `createProject`       | Create a project                                               |
    | `updateProject`       | Update a project                                               |
    | `deleteProject`       | Delete a project                                               |
    | `getProjectMetrics`   | Get project's metrics                                          |
    | `listProjectsMetrics` | List projects metrics                                          |
    | `exportProjects`      | Get projects export file (`csv`/`xlsx`)                        |

    ### Tasks

    | Tool         | Description   |
    | ------------ | ------------- |
    | `listTasks`  | List tasks    |
    | `getTask`    | Get a task    |
    | `createTask` | Create a task |
    | `updateTask` | Update a task |
    | `deleteTask` | Delete a task |

    ### Declarations

    | Tool                   | Description                                            |
    | ---------------------- | ------------------------------------------------------ |
    | `listDeclarations`     | List declarations (requires `task_ids` and `user_ids`) |
    | `createDeclaration`    | Create a declaration                                   |
    | `updateDeclaration`    | Update a declaration                                   |
    | `deleteDeclaration`    | Delete a declaration                                   |
    | `exportTimesAndLeaves` | Get declaration and leaves export file                 |

    ### Leave Periods

    | Tool                 | Description           |
    | -------------------- | --------------------- |
    | `listLeavesPeriods`  | List leaves periods   |
    | `getLeavesPeriod`    | Get a leave period    |
    | `createLeavesPeriod` | Create a leave period |
    | `updateLeavesPeriod` | Update a leave period |
    | `deleteLeavesPeriod` | Delete a leave period |

    ### Discounts & Purchases

    | Tool                                                                                     | Description                   |
    | ---------------------------------------------------------------------------------------- | ----------------------------- |
    | `listDiscounts` / `getDiscount` / `createDiscount` / `updateDiscount` / `deleteDiscount` | Manage project/task discounts |
    | `listPurchases` / `getPurchase` / `createPurchase` / `updatePurchase` / `deletePurchase` | Manage project/task purchases |

    ### Users, Groups, Tags

    | Tool                                                        | Description                      |
    | ----------------------------------------------------------- | -------------------------------- |
    | `listUsers` / `getUser` / `inviteUser`                      | List, fetch and invite users     |
    | `listGroups` / `getGroup` / `listGroupsets` / `getGroupset` | Browse user groups and groupsets |
    | `listTags` / `getTag` / `listTagsets` / `getTagset`         | Browse tags and tagsets          |

    ## Tool Details

    ### createDeclaration

    Log a time entry on a task for a specific user.

    ```json theme={null}
    {
      "name": "createDeclaration",
      "arguments": {
        "user_id": "user-uuid",
        "task_id": "task-uuid",
        "date": "2026-04-20",
        "duration": 7200,
        "description": "Implementation review"
      }
    }
    ```

    | Parameter     | Required | Description                     |
    | ------------- | -------- | ------------------------------- |
    | `date`        | Yes      | Declaration date (`YYYY-MM-DD`) |
    | `duration`    | Yes      | Duration in seconds             |
    | `task_id`     | Yes      | UUID of the task                |
    | `user_id`     | Yes      | UUID of the user                |
    | `description` | No       | Free-form text, max 256 chars   |

    ### createProject

    ```json theme={null}
    {
      "name": "createProject",
      "arguments": {
        "name": "Website Revamp",
        "start_at": "2026-01-06",
        "customer_id": "customer-uuid",
        "visibility": "private",
        "is_billable": true,
        "managers": ["manager-uuid"]
      }
    }
    ```

    Accepts `code`, `end_at`, `contributors`, `groups`, `tags`. `visibility` is one of `public` / `private` — `contributors` must be empty when `visibility="public"`.

    ### createTask

    ```json theme={null}
    {
      "name": "createTask",
      "arguments": {
        "project_id": "project-uuid",
        "name": "Design System",
        "start_at": "2026-01-06",
        "budget_type": "time",
        "planned_duration": 80
      }
    }
    ```

    `budget_type` ∈ `none`/`detailed`/`global`/`time`. `hourly_rate_mode` ∈ `task`/`group`/`contributor`. Supports `parent_id` for sub-tasks and `is_container` for parent tasks.

    ### createLeavesPeriod

    ```json theme={null}
    {
      "name": "createLeavesPeriod",
      "arguments": {
        "user_id": "user-uuid",
        "start_at": "2026-05-10",
        "end_at": "2026-05-14",
        "start_type": "full",
        "end_type": "full",
        "description": "Vacation"
      }
    }
    ```

    `start_type` / `end_type` ∈ `full` / `am` / `pm`. Use `delete_declaration: true` to remove existing declarations in that range.

    ### inviteUser

    ```json theme={null}
    {
      "name": "inviteUser",
      "arguments": {
        "email": "new.hire@example.com",
        "role": "contributor",
        "group_ids": ["group-uuid"]
      }
    }
    ```

    `role` ∈ `contributor` / `collaborator` / `manager` / `director` / `admin`.

    ### exportTimesAndLeaves / exportProjects

    Generate payroll-grade exports over a date range.

    ```json theme={null}
    {
      "name": "exportTimesAndLeaves",
      "arguments": {
        "from": "2026-03-01",
        "to": "2026-03-31",
        "type": 1
      }
    }
    ```

    `exportProjects` accepts `type` ∈ `csv` / `xlsx` and an optional `project_ids` filter.
  </Tab>
</Tabs>

***

## Error Handling

| HTTP Status | Error        | Solution                                                                     |
| ----------- | ------------ | ---------------------------------------------------------------------------- |
| 401         | Unauthorized | Verify the API key and `baseUrl`                                             |
| 403         | Forbidden    | Check the Gryzzly role of the API key owner                                  |
| 404         | Not Found    | Verify UUIDs for project, task, user, etc.                                   |
| 422         | Validation   | Check required fields and enum values (roles, visibility, budget type, etc.) |
| 429         | Rate Limited | Back off and retry with exponential delay                                    |

### Common Issues

**"Not configured"** — The app instance has no API key. Generate one in *Gryzzly > Administration > API Keys* and paste it in the app configuration.

**"Invalid API key" (MCP)** — The `mcp-api-key` header does not match the central app secret. Reinstall the app instance to regenerate a signed key.

**"Credentials lookup failed"** — The MCP endpoint could not reach the `getConfig` webhook of the installed app. Verify that the app instance is still installed in the expected workspace.

**`contributors` rejected on public project** — Set `visibility: private` or leave `contributors` empty.

## External Resources

<CardGroup cols={2}>
  <Card title="Gryzzly API" icon="book" href="https://api.gryzzly.io/v1/docs">
    Official Gryzzly API documentation
  </Card>

  <Card title="Tool Agents" icon="robot" href="/products/agent-factory/capabilities">
    Plug MCP servers into Knowledges agents
  </Card>
</CardGroup>