API Overview

The Vizco REST API provides full access to all platform resources — organizations, projects, assets, folders, widgets, and API keys.

Base URL

All API requests are made to your Vizco backend instance:

https://your-api.com

Content types

• Request body — application/json for all endpoints except file upload.
• File upload — multipart/form-data for asset upload.
• Response body — application/json for all endpoints except asset delivery (which returns raw image bytes).

Authentication

Two authentication methods are supported:

| Method | Header | Use case | |---|---|---| | JWT Bearer | Authorization: Bearer {token} | Management operations | | API Key | X-API-Key: pk_... | Public widget delivery |

See Authentication for details.

Error format

Error responses follow a consistent format:

{
"status": 404,
"error": "Not Found",
"message": "Widget not found with slug: hero-carousel",
"path": "/api/v1/widgets/hero-carousel",
"timestamp": "2026-01-15T10:30:00"
}

Common status codes

| Code | Meaning | |---|---| | 200 | Success | | 201 | Created | | 204 | No content (successful deletion) | | 400 | Bad request (validation error) | | 401 | Unauthorized (missing or invalid auth) | | 403 | Forbidden (insufficient permissions) | | 404 | Resource not found | | 409 | Conflict (e.g. duplicate slug) | | 500 | Internal server error |

Pagination

The asset list endpoint supports pagination:

GET /api/projects/{projectId}/assets?page=0&size=20

Paginated responses include metadata:

{
"content": [...],
"totalElements": 45,
"totalPages": 3,
"size": 20,
"number": 0,
"first": true,
"last": false
}

UUIDs

All resource identifiers are UUIDs (v4). Example: 550e8400-e29b-41d4-a716-446655440000

Timestamps

All timestamps are in ISO 8601 format without timezone (server local time): 2026-01-15T10:30:00