103 lines
2.5 KiB
Markdown
103 lines
2.5 KiB
Markdown
# api-basics
|
||
|
||
Core conventions for the Prisma Management API. All three `prisma-postgres-*` skills share these patterns.
|
||
|
||
## Base URL
|
||
|
||
```
|
||
https://api.prisma.io/v1
|
||
```
|
||
|
||
API documentation: https://api.prisma.io/v1/doc
|
||
|
||
## Response Envelope
|
||
|
||
### Single resource
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "proj_clx7abc123def456",
|
||
"type": "project",
|
||
"name": "My Project",
|
||
"createdAt": "2025-06-15T10:30:00.000Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Collection
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{ "id": "proj_aaa", "type": "project", "name": "Alpha" },
|
||
{ "id": "proj_bbb", "type": "project", "name": "Beta" }
|
||
],
|
||
"pagination": {
|
||
"hasMore": true,
|
||
"nextCursor": "clx7cursor123"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Resource ID Prefixes
|
||
|
||
Every resource ID carries a type prefix:
|
||
|
||
| Prefix | Resource |
|
||
|---|---|
|
||
| `proj_` | Project |
|
||
| `db_` | Database |
|
||
| `con_` | Connection |
|
||
| `wksp_` | Workspace |
|
||
|
||
Always include the prefix when sending IDs in API requests.
|
||
|
||
## Pagination
|
||
|
||
Collection endpoints use cursor-based pagination:
|
||
|
||
```
|
||
GET /v1/projects?limit=10
|
||
GET /v1/projects?cursor=clx7abc123&limit=10
|
||
```
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|---|---|---|---|
|
||
| `cursor` | string | — | Opaque cursor from `nextCursor` |
|
||
| `limit` | number | 100 | Maximum items per page |
|
||
|
||
Continue fetching while `pagination.hasMore` is `true`, using `pagination.nextCursor` as the `cursor` parameter.
|
||
|
||
## Error Responses
|
||
|
||
All errors follow this shape:
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "resource-not-found",
|
||
"message": "database with id db_abc not found"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Error codes by HTTP status
|
||
|
||
| HTTP Status | Error Code | Meaning |
|
||
|---|---|---|
|
||
| 400 | `client-error` | Malformed request |
|
||
| 401 | `authentication-failed` | Missing or invalid token |
|
||
| 403 | `permission-denied` | Token lacks required access |
|
||
| 404 | `resource-not-found` | Resource does not exist or is not accessible |
|
||
| 422 | `validation-error` | Request body failed validation |
|
||
| 429 | `rate-limit-exceeded` | Too many requests |
|
||
| 500 | `internal-server-error` | Server error — retry after a delay |
|
||
|
||
### Self-correction patterns
|
||
|
||
- **401**: Token is invalid or expired. Create a new service token in Console → Workspace Settings → Service Tokens.
|
||
- **404**: Verify the resource ID includes the correct prefix (`proj_`, `db_`, `con_`). Use `GET /v1/projects` or `GET /v1/databases` to list available resources.
|
||
- **422**: Check the request body against the endpoint schema. Common issues: missing required fields, invalid region ID, empty `name`.
|
||
- **429**: Wait 2–5 seconds and retry. If repeated, increase the backoff interval.
|