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

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# api fetch

> Call any Base44 API operation from the command line

Call any [Apps API](/developers/references/apps-api/get-started/overview) or [Workspace API](/developers/references/workspace-api/get-started/overview) operation from your terminal. The command uses the account you signed in with using [`login`](/developers/references/cli/commands/login), so there's nothing else to set up. Pass the HTTP method and the path, and the command returns the server's response. Find the path with [`api search`](/developers/references/cli/commands/api-search) or [`api catalog`](/developers/references/cli/commands/api-catalog).

Paths from the spec contain placeholders in braces, such as `{app_id}` and `{workflow_id}`. The command fills in `{app_id}` from `--app-id`, the `BASE44_APP_ID` environment variable, or the linked project. Replace any other placeholder with a real value before you send the request.

The command doesn't check the request before sending it. If something's wrong, you get the server's error message and a request ID. When you've hit a [rate limit](/developers/references/apps-api/get-started/rate-limits), the error also says how long to wait before trying again.

The command doesn't time out, so a slow operation such as a deploy still returns its response, even if it takes minutes.

To see what an operation expects before you call it, add `--help` after the method and path. The command prints the operation's contract as JSON, with its parameters, request body schema, and response schema, and sends nothing.

## Usage

```bash theme={null}
base44 api fetch <method> <path>
```

## Arguments

| Argument | Description | Required |
| - | - | - |
| `<method>` | The HTTP method, for example `GET` or `POST`. | Yes |
| `<path>` | The operation's path, starting with `/api`, with any query string. Leave `{app_id}` in for the command to fill in, and replace any other placeholder with a real value. Quote the path so your shell doesn't read the braces or the `?`. | Yes |

## Flags

| Flag | Description |
| - | - |
| `--app-id <id>` | Target the specified app. Defaults to the app linked in the current project. See [Select a target app](/developers/references/cli/commands/introduction#select-a-target-app). |
| `--body <json>` | The request body as JSON. Pass `@file.json` to read it from a file, or `@-` to read it from stdin. |
| `--form <field>` | Send a multipart form field, for operations that upload files. Use `name=value` for a field and `name=@path` to attach a file. Add `;type=<media type>` after the path to set the file's content type. Repeat the flag for each field. Can't be combined with `--body`. |
| `--output <file>` | Save the response body to a file instead of returning it. Use this for a binary response, such as a downloaded archive. |
| `--read-only` | Only send the request if the operation can't change anything. The command checks the API spec first and refuses any operation that isn't marked read-only, without sending it. Use it when an AI agent or a script runs the command for you. |
| `--refresh` | Get the latest list of operations from the server instead of the copy the CLI saved, which it keeps for up to an hour. Use it when `--help` or `--read-only` can't find an operation that was added recently. It has no effect without one of those flags. |
| `-h, --help` | After a method and path, print that operation's contract. On its own, print the command's help. |

## Example

Check what an operation expects, then call it:

```bash theme={null}
base44 api fetch GET "/api/apps/{app_id}/workflows/runs" --help
base44 api fetch GET "/api/apps/{app_id}/workflows/runs?status=failed&limit=10"
```

List a workspace's groups. Workspace API operations take the workspace ID as a `workspaceId` query parameter, which the command doesn't fill in for you. Run [`workspace list`](/developers/references/cli/commands/workspace-list) to find it:

```bash theme={null}
base44 api fetch GET "/api/workspace/groups?workspaceId=507f1f77bcf86cd799439011"
```

Import records into an entity from a CSV file, sent as a multipart form field:

```bash theme={null}
base44 api fetch POST "/api/apps/{app_id}/entities/Task/import" --form "file=@tasks.csv;type=text/csv"
```

## Output

The command returns the response body as the server sent it. In a terminal, JSON is formatted so it's easier to read. When you pipe the output to another program, it's passed through unchanged, so large numbers aren't rounded.

When the body is empty, binary, or saved to a file, the command returns a short JSON summary instead of the body:

| Response | Displayed summary |
| - | - |
| Empty body | The HTTP `status` code, for example `{"status": 204}`. |
| Binary body | The `status`, the `contentType`, and the body's size in `bytes`. The body itself isn't shown. Pass `--output` to save it to a file. |
| Saved with `--output` | The `status`, the `contentType`, the body's size in `bytes`, and the `output` file path. |

## See also

* [`api grep`](/developers/references/cli/commands/api-grep): Search the API spec with a regular expression
* [`exec`](/developers/references/cli/commands/exec): Run a script with the Base44 SDK pre-authenticated
* [Base44 APIs](/developers/references/apis/overview): The REST APIs and their references


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.