REST API Reference

The Ycode public v1 API provides programmatic access to collections, items, forms, and submissions. Use it to build custom integrations, sync data, or power external applications.

Base URL

https://your-project.ycode.dev/ycode/api/v1

Replace your-project with your project subdomain or custom domain.

Authentication

All requests require a Bearer token (API key) in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create API keys in project settings under Integrations > API Keys. Invalid or missing keys return 401 Unauthorized.

Request Format

• Content-Type: application/json for request bodies
• Accept: application/json for responses

Response Format

Successful responses return JSON. List endpoints include pagination metadata:

{
  "items": [...],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 100
  }
}

Single-resource endpoints return the resource directly as a JSON object.

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Collections Endpoints

List Collections

GET /ycode/api/v1/collections

Returns all collections in the project.

Get Collection

GET /ycode/api/v1/collections/:id

Returns a single collection by ID, including field definitions.

List Items

GET /ycode/api/v1/collections/:id/items

Query parameters:

Example request with filtering and sorting:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-project.ycode.dev/ycode/api/v1/collections/:id/items?sort_by=name&order_by=desc&filter[status]=active&per_page=50"

Response:

{
  "items": [
    { "id": "...", "name": "...", "slug": "...", ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 12
  }
}

Get Item

GET /ycode/api/v1/collections/:id/items/:itemId

Returns a single collection item by ID.

Create Item

POST /ycode/api/v1/collections/:id/items

Creates a new item in the collection. The item is created as published immediately.

Send a JSON body with field slugs as keys and their values:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Blog Post", "slug": "new-blog-post", "content": "Hello world"}' \
  "https://your-project.ycode.dev/ycode/api/v1/collections/:id/items"

The id, created_at, and updated_at fields are generated automatically and cannot be set manually.

Returns the created item with status 201.

Update Item (Full)

PUT /ycode/api/v1/collections/:id/items/:itemId

Replaces all field values on an item. Fields not included in the request body are cleared to null. Use this when you want to overwrite the entire item.

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Title", "slug": "updated-title", "content": "New content"}' \
  "https://your-project.ycode.dev/ycode/api/v1/collections/:id/items/:itemId"

The id, created_at, and updated_at fields are protected and cannot be overwritten. The updated_at timestamp is set automatically.

Returns the updated item.

Update Item (Partial)

PATCH /ycode/api/v1/collections/:id/items/:itemId

Updates only the fields included in the request body. All other fields remain unchanged. Use this when you want to modify specific fields without affecting the rest.

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Title"}' \
  "https://your-project.ycode.dev/ycode/api/v1/collections/:id/items/:itemId"

Returns the updated item.

Delete Item

DELETE /ycode/api/v1/collections/:id/items/:itemId

Permanently deletes an item and its associated data.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-project.ycode.dev/ycode/api/v1/collections/:id/items/:itemId"

Returns a confirmation:

{
  "deleted": true,
  "_id": "item-uuid"
}

Forms Endpoints

List Forms

GET /ycode/api/v1/forms

Returns all forms in the project.

Get Form

GET /ycode/api/v1/forms/:id

Returns a single form by ID, including field definitions.

List Submissions

GET /ycode/api/v1/forms/:id/submissions

Returns submissions for the form. Supports pagination.

Create Submission

POST /ycode/api/v1/forms/:id/submissions

Body: JSON object with form field names as keys and submitted values. Creates a new submission.

Get Submission

GET /ycode/api/v1/forms/:id/submissions/:submissionId

Returns a single submission by ID.