redesign: replace docs with new IA from Pixee-Marketing-OS PR #117

docs/api/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "API & Reference",
+  "position": 8,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "api/api-overview"
+  }
+}

docs/api/api-overview.md

@@ -0,0 +1,175 @@
+---
+title: API Overview
+slug: /api/overview
+track: dev
+content_type: reference
+seo_title: API Overview -- Pixee Docs
+description: "Pixee REST API reference: authentication, endpoints, rate limits, and SARIF input format."
+sidebar_position: 1
+---
+
+# API Overview
+
+Pixee provides a REST API for programmatic access to vulnerability triage and remediation workflows. The API enables querying fix status, managing repository configurations, consuming webhook events for CI/CD integration, and ingesting SARIF scanner output. Authentication uses organization-scoped API tokens. This page covers available endpoints, authentication, rate limits, and links to detailed specifications.
+
+## API architecture
+
+The Pixee API follows standard REST conventions:
+
+- **Protocol:** HTTPS only. All requests must use TLS.
+- **Format:** JSON request and response bodies. Responses include standard HTTP status codes.
+- **Base URL:** `https://app.pixee.ai/api/v1`
+- **Versioning:** Path-based (`/v1/`). Breaking changes ship under a new version prefix.
+
+## Authentication
+
+Pixee uses bearer tokens for API authentication. Tokens are scoped to your organization and generated from the Pixee dashboard.
+
+**Generate a token:**
+
+1. Navigate to **Settings > API Tokens** in the Pixee dashboard.
+2. Click **Create Token**.
+3. Name the token and select the scope (organization-wide or repository-specific).
+4. Copy the token immediately. It is displayed only once.
+
+**Include the token in every request:**
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_TOKEN" \
+     https://app.pixee.ai/api/v1/repositories
+```
+
+```python
+import requests
+
+headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
+response = requests.get(
+    "https://app.pixee.ai/api/v1/repositories",
+    headers=headers
+)
+repositories = response.json()
+```
+
+**Token best practices:**
+
+- Rotate tokens every 90 days.
+- Use repository-scoped tokens for CI/CD pipelines that operate on a single repository.
+- Store tokens in your secrets manager (Vault, AWS Secrets Manager, GitHub Actions secrets). Never commit tokens to source control.
+
+## Rate limits
+
+| Tier       | Requests per minute | Burst |
+| ---------- | ------------------- | ----- |
+| Standard   | 60                  | 10    |
+| Enterprise | 300                 | 50    |
+
+Rate-limited responses return `429 Too Many Requests` with a `Retry-After` header indicating seconds until the next available request window.
+
+## Available endpoints
+
+| Category     | Method   | Endpoint                      | Description                                      |
+| ------------ | -------- | ----------------------------- | ------------------------------------------------ |
+| Repositories | `GET`    | `/repositories`               | List repositories connected to your organization |
+| Repositories | `GET`    | `/repositories/{id}`          | Get repository configuration and status          |
+| Repositories | `PATCH`  | `/repositories/{id}`          | Update repository settings                       |
+| Fixes        | `GET`    | `/repositories/{id}/fixes`    | List fix results for a repository                |
+| Fixes        | `GET`    | `/fixes/{id}`                 | Get fix details including diff and rationale     |
+| Scans        | `GET`    | `/repositories/{id}/scans`    | List scan history                                |
+| Scans        | `POST`   | `/repositories/{id}/scans`    | Trigger a new scan                               |
+| Triage       | `GET`    | `/repositories/{id}/findings` | List triaged findings                            |
+| Triage       | `GET`    | `/findings/{id}`              | Get finding details and triage classification    |
+| Webhooks     | `POST`   | `/webhooks`                   | Register a webhook endpoint                      |
+| Webhooks     | `GET`    | `/webhooks`                   | List registered webhooks                         |
+| Webhooks     | `DELETE` | `/webhooks/{id}`              | Remove a webhook                                 |
+
+For webhook event types and payload schemas, see [Webhooks](/api/webhooks).
+
+## Error handling
+
+All error responses use a consistent JSON structure:
+
+```json
+{
+  "error": {
+    "code": "not_found",
+    "message": "Repository with ID 'abc123' not found.",
+    "request_id": "req_7f8a9b2c"
+  }
+}
+```
+
+| Status code | Meaning                                                                                             |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| `400`       | Bad request. Check request body and parameters.                                                     |
+| `401`       | Invalid or missing API token.                                                                       |
+| `403`       | Token does not have permission for this resource.                                                   |
+| `404`       | Resource not found.                                                                                 |
+| `429`       | Rate limit exceeded. Retry after the interval in the `Retry-After` header.                          |
+| `500`       | Internal server error. Retry with exponential backoff. Include the `request_id` in support tickets. |
+
+## Quick start
+
+List your repositories and retrieve recent fix results in two calls:
+
+```bash
+# 1. List repositories
+curl -s -H "Authorization: Bearer $PIXEE_TOKEN" \
+     https://app.pixee.ai/api/v1/repositories | jq '.data[].name'
+
+# 2. Get fixes for a repository
+curl -s -H "Authorization: Bearer $PIXEE_TOKEN" \
+     https://app.pixee.ai/api/v1/repositories/REPO_ID/fixes | jq '.data[:3]'
+```
+
+```python
+import requests
+
+TOKEN = "YOUR_API_TOKEN"
+BASE = "https://app.pixee.ai/api/v1"
+headers = {"Authorization": f"Bearer {TOKEN}"}
+
+# List repositories
+repos = requests.get(f"{BASE}/repositories", headers=headers).json()
+repo_id = repos["data"][0]["id"]
+
+# Get recent fixes
+fixes = requests.get(
+    f"{BASE}/repositories/{repo_id}/fixes",
+    headers=headers,
+    params={"limit": 5}
+).json()
+
+for fix in fixes["data"]:
+    print(f"{fix['codemod']} - {fix['status']} - {fix['pr_url']}")
+```
+
+## Input format
+
+Pixee consumes scanner output in **SARIF** -- the OASIS standard for static analysis results -- from natively integrated scanners and any SARIF-producing tool. See the [SARIF Reference](/api/sarif).
+
+## SDKs and OpenAPI specification
+
+An OpenAPI 3.0 specification is available for generating client libraries in any language:
+
+```bash
+curl -o pixee-openapi.json \
+     https://app.pixee.ai/api/v1/openapi.json
+```
+
+Use the specification with standard code generators:
+
+```bash
+# Python client
+openapi-python-client generate --path pixee-openapi.json
+
+# TypeScript client
+npx @openapitools/openapi-generator-cli generate \
+    -i pixee-openapi.json -g typescript-fetch
+```
+
+## Related pages
+
+- [SARIF Reference](/api/sarif) -- How Pixee consumes SARIF from scanners
+- [Webhooks](/api/webhooks) -- Event-driven integration for CI/CD and automation
+- [CI/CD Integration](/integrations/ci-cd) -- Common API consumer patterns
+- [Configuration Overview](/configuration/overview) -- Repository management

docs/api/cli.md

@@ -0,0 +1,147 @@
+---
+title: Pixee CLI
+slug: /api/cli
+track: dev
+content_type: tutorial
+seo_title: "Pixee CLI | Command-Line Client for the Pixee Platform"
+description: Install the Pixee CLI to authenticate against a Pixee deployment and drive the REST API from your terminal, scripts, or coding agents.
+sidebar_position: 6
+---
+
+The Pixee CLI (`pixee`) is the command-line client for the Pixee platform. It authenticates against a Pixee deployment, exposes dedicated subcommands for the most common operations (listing repositories, inspecting scans, configuring workflows), and provides a generic `pixee api` passthrough for any other REST endpoint. The CLI is intended for Pixee customers — it talks _to_ a Pixee deployment, it does not run analysis or generate fixes locally. Source distribution: [github.com/pixee/pixee-cli](https://github.com/pixee/pixee-cli).
+
+## When to Use the CLI
+
+The CLI complements the SCM integrations (GitHub App, GitLab, Azure DevOps, Bitbucket); it does not replace them. Triage and remediation continue to run on the Pixee platform, triggered by your SCM integration. Use the CLI when you need to:
+
+- **Query platform state from scripts.** List registered repositories, fetch scan history, inspect workflows.
+- **Configure workflows from the command line.** Create, update, or delete schedule / new-scan / pull-request-scan workflows on a repository.
+- **Drive the API from a coding agent.** Bundled `skills.sh`-formatted skills teach Claude Code, OpenAI Codex, and other agents how to use the CLI safely.
+- **Hit any REST endpoint without writing curl.** The `pixee api` subcommand handles authentication, pagination, and HAL link traversal.
+
+## Installation
+
+### Homebrew (macOS and Linux)
+
+```bash
+brew tap pixee/pixee
+brew install pixee
+```
+
+### Direct download
+
+Pre-compiled binaries for `linux-x64`, `darwin-arm64`, and `windows-x64` are published as assets on every [GitHub Release](https://github.com/pixee/pixee-cli/releases/latest). Download the archive, extract `pixee`, place it on your `PATH`.
+
+Verify:
+
+```bash
+pixee --version
+```
+
+## Authenticate
+
+You need a Pixee API token (generated from the admin console's **API Tokens** page) and the URL of your Pixee deployment.
+
+```bash
+# Interactive login — stores token + server in a platform-appropriate config file.
+pixee auth login --server https://pixee.example.com --token pixee_xxx
+
+# Stdin form — keeps the token off the command line and out of shell history.
+echo -n "$PIXEE_TOKEN" | pixee auth login --server https://pixee.example.com --token -
+
+# Confirm.
+pixee auth status
+# Logged in to https://pixee.example.com as api-token
+# Token: valid
+```
+
+The token is written with `0600` permissions on Unix; Windows inherits the per-user directory's NTFS ACL.
+
+**Credential resolution.** For every subcommand except `pixee auth login`, the CLI resolves credentials in this order:
+
+- **Token:** `PIXEE_TOKEN` env var → stored config.
+- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config.
+
+Setting `PIXEE_TOKEN` and `PIXEE_SERVER` is the standard CI/CD path — no `pixee auth login` step is required in pipelines.
+
+## Common Commands
+
+| Command                                                             | What It Does                                                                                         |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `pixee repo list`                                                   | List repositories registered with the platform. Filter with `--name <pattern>`.                      |
+| `pixee scan list --repo <name>`                                     | List scans for a repository. Filter with `--branch`, `--tool`, `--analysis-state`, `--has-analysis`. |
+| `pixee scan get <id>`                                               | Fetch a single scan by UUID.                                                                         |
+| `pixee workflow list --repo <name>`                                 | List workflows on a repository.                                                                      |
+| `pixee workflow create schedule --repo <name> --cadence weekly ...` | Create a schedule workflow. Sibling subcommands: `new-scan`, `pull-request-scan`.                    |
+| `pixee workflow update <id> ...`                                    | Update an existing workflow (partial-update semantics).                                              |
+| `pixee workflow delete <id>`                                        | Remove a workflow.                                                                                   |
+| `pixee api /api/v1/repositories --paginate`                         | Send an authenticated GET to any endpoint, walking pagination.                                       |
+| `pixee api /api/v1/<path> --method POST --input body.json`          | POST a JSON body.                                                                                    |
+| `pixee --help`                                                      | Show all available commands.                                                                         |
+| `pixee <command> --help`                                            | Show command-specific flags.                                                                         |
+
+The dedicated subcommands cover the common cases. `pixee api` is the escape hatch — use it when a dedicated subcommand does not yet exist, or when a coding agent needs to compose multi-step operations directly.
+
+## Output Format
+
+All subcommands accept `--output text` (default — flat, line-oriented, suitable for `grep`/`awk`) or `--output json` (machine-readable, pipe to `jq`). The `--json` shorthand is equivalent to `--output json`.
+
+```bash
+pixee repo list --json | jq '.[] | select(.type == "github") | .full_name'
+```
+
+## Exit Codes
+
+Scripts and agents can branch on these without parsing stderr:
+
+| Code | Meaning                                                                   |
+| ---- | ------------------------------------------------------------------------- |
+| 0    | Success                                                                   |
+| 1    | General error                                                             |
+| 2    | Authentication failure (token missing, expired, invalid, or wrong server) |
+| 3    | Resource not found                                                        |
+
+Errors from the Pixee API are returned as `application/problem+json`. With `--output text`, the CLI renders the problem document in compact human-readable form; with `--output json` the raw document passes through unchanged.
+
+## HAL Discovery via `pixee api`
+
+The Pixee REST API is a HAL (Hypertext Application Language) API. Every response includes `_links` to related resources. Start at `/api/v1` and follow links rather than hardcoding paths:
+
+```bash
+# Inspect the root.
+pixee api /api/v1
+
+# Follow the "repositories" link.
+pixee api /api/v1/repositories --paginate
+
+# Drill into a specific repository — its _links lead to scans, workflows, etc.
+pixee api /api/v1/repositories/<id>
+```
+
+## Coding-Agent Skills
+
+The CLI ships [skills.sh](https://skills.sh)-formatted skills that teach coding agents (Claude Code, OpenAI Codex, and others) how to drive the CLI without you re-explaining the conventions every time. Skills cover global flags and exit codes (`pixee-shared`), authentication (`pixee-auth`), the `pixee api` escape hatch (`pixee-api`), and each command group (`pixee-repo`, `pixee-scan`, `pixee-workflow`).
+
+```bash
+# Install all skills.
+npx skills add pixee/pixee-cli --all
+
+# Or pick interactively.
+npx skills add pixee/pixee-cli
+```
+
+The skills are licensed separately under Apache 2.0 and live in the [`skills/`](https://github.com/pixee/pixee-cli/tree/main/skills) directory of the CLI repo.
+
+## CLI in CI/CD
+
+The CLI is well-suited to running inside CI: set `PIXEE_TOKEN` and `PIXEE_SERVER` as secrets, install the binary, and call any subcommand. Common patterns:
+
+```bash
+# Inspect platform state during a release pipeline.
+pixee scan list --repo "$REPO" --branch main --tool codeql --json
+
+# Create or update a workflow as part of repository provisioning.
+pixee workflow create new-scan --repo "$REPO" --tool codeql ...
+```
+
+The CLI does not run analysis or generate fixes — those happen on the platform, triggered by your SCM integration. See [CI/CD Integration](/integrations/ci-cd) for the end-to-end pipeline patterns.