# VibeSKU Developer Guide

## Overview

VibeSKU exposes authenticated API and CLI workflows for generating e-commerce product visuals and listing copy. Agents should prefer the OpenAPI specification at [https://vibesku.com/openapi.json](https://vibesku.com/openapi.json) for exact request and response schemas.

## Authentication

Use bearer authentication:

```http
Authorization: Bearer vsk_your_key
```

Supported credentials:

- API keys beginning with `vsk_`, created in [dashboard settings](https://vibesku.com/dashboard/settings).
- CLI tokens beginning with `vst_`, created with `vibesku auth login`.

VibeSKU API keys are account-level bearer credentials today. Do not assume granular per-endpoint scopes unless a future API response explicitly publishes them.

## Endpoint map

- `GET /api/v1/auth/verify` verifies credentials and returns user, plan, and key metadata.
- `GET /api/v1/templates` lists template IDs, required assets, brief fields, and options.
- `POST /api/v1/assets/upload` uploads product images or logos.
- `POST /api/v1/generate` creates a generation job.
- `GET /api/v1/jobs` lists jobs.
- `GET /api/v1/jobs/{jobId}` returns job status, active runs, and outputs.
- `GET /api/v1/jobs/{jobId}/download` returns downloadable output URLs.
- `POST /api/v1/outputs/{outputId}/refine` refines a generated output.
- `GET /api/v1/credits` returns credit balance.
- `GET /api/v1/pricing` returns authenticated pricing catalog data.
- `POST /api/v1/checkout` creates a checkout URL.
- `POST /api/v1/redeem` redeems a credit code.

## Rate limits

API key requests include:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

When a request exceeds the limit, the API returns `429 RATE_LIMIT_EXCEEDED` with structured JSON and `Retry-After`.

## Error format

Errors use JSON:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_AUTH",
    "message": "Missing or invalid Authorization header.",
    "details": null
  },
  "meta": {
    "requestId": "request-id",
    "timestamp": "2026-05-12T00:00:00.000Z"
  }
}
```

## Agent workflow

1. Authenticate with a bearer key or CLI token.
2. Fetch templates.
3. Upload product imagery when needed.
4. Submit a generation job.
5. Poll job status.
6. Download or refine outputs.