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

# Raw customer API command

> Call an existing customer API path with bounded inputs, safe retries, downloads, and path restrictions.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Use a customer API operation that has no higher-level CLI workflow without leaving the customer boundary.

## Prerequisites

* An authenticated profile
* The method, path, and request shape from StackShift customer API documentation

## Workflow

<Steps>
  <Step>
    Confirm that no purpose-built CLI command already covers the workflow.
  </Step>

  <Step>
    Choose an allowed method and customer API path.
  </Step>

  <Step>
    Supply at most one request body source.
  </Step>

  <Step>
    Mark a write idempotent only when the API contract guarantees it.
  </Step>

  <Step>
    Select structured output or a safe download destination.
  </Step>
</Steps>

## Syntax and allowed methods

The method must be GET, POST, PUT, PATCH, or DELETE. The path must be relative, start with `/api/v1/`, `/v1/`, or `/v2/`, and remain on the configured API host.

```bash theme={null}
stackshift api METHOD /PATH [flags]
stackshift api GET /api/v1/projects/
stackshift api PATCH /api/v1/user --file user-update.json
```

## Blocked paths

Decoded paths are normalized and rejected when they contain traversal. The first path segment after any allowed customer prefix cannot be one of these internal namespaces.

* `admin`
* `internal`
* `agent`
* `webhooks`
* `portal`
* `compute-runner`

## Request bodies

`--data` accepts an inline body. `--file` reads a body from a path, or from standard input when its value is `-`. Inputs are limited to 16 MiB. The raw command sends the body as `application/json` but does not invent or transform API fields.

```bash theme={null}
stackshift api PATCH /api/v1/user --data '{"name": "Example"}'
stackshift api PATCH /api/v1/user --file user-update.json
generate-user-update | stackshift api PATCH /api/v1/user --file -
```

## Idempotent writes and retries

GET requests may retry automatically. Add `--idempotent` to a write only when the documented endpoint safely supports repeated requests. The CLI then creates an idempotency key and permits retry on 429, 502, 503, and 504 responses.

## Downloads

`--download` is valid only with GET and cannot be combined with request data. The destination is created with mode `0600`, existing files are never replaced, and partial files are removed after copy, close, cancellation, or size failure.

Raw API downloads are capped at 2 GiB.

```bash theme={null}
stackshift api GET /api/v1/exports/EXPORT_ID/archive \
  --download ./stackshift-export.tar.gz
```

## Output and diagnostics

Non-download responses use the same table, JSON, and YAML printers as resource commands. Sensitive structured fields and query values are redacted. Use `--debug` to inspect the method and redacted URL on standard error.

## Expected result

<Check>
  The customer API response is printed or downloaded without permitting internal platform access.
</Check>

## Common failures

<Warning>
  * An absolute URL is supplied instead of a relative API path.
  * The path targets a blocked admin, internal, agent, webhook, portal, or runner route.
  * `--download` is used with a write or request data.
  * The download destination already exists.
  * `--idempotent` is used without verifying the endpoint contract.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Resource command model and coverage" href="/cli/resource-commands">
    Use consistent list, read, write, pagination, request body, resolution, and confirmation behavior.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>
</CardGroup>