Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HelenaLM32/ECHO/llms.txt

Use this file to discover all available pages before exploring further.

Projects are rich portfolio showcases that creators publish on ECHO. Unlike services, which describe an offering, projects display completed work using a flexible block-based content system. Each project is composed of a blocks array — a JSON structure where each element represents a content block such as an image, text section, or embed. Projects also track engagement through likes, views, and comments counters. Only projects marked as published are publicly visible; drafts remain hidden until the creator explicitly publishes them.
Projects share the same id as their linked item — the id in item_projects is a foreign key to items.id. Create the item first before creating its project record.

​
Get all projects

GET /item-projects Returns all project records. This endpoint is public and does not require authentication. 
curl -X GET http://localhost:8084/item-projects
Response 
[
  {
    "id": 10,
    "blocks": "[{\"type\":\"image\",\"url\":\"https://cdn.example.com/work/cover.jpg\"},{\"type\":\"text\",\"content\":\"A brand identity project for a local coffee shop.\"}]",
    "background": "#F5F5F0",
    "blockGap": 24,
    "likes": 142,
    "views": 3800,
    "comments": 17,
    "published": true,
    "slug": "coffee-shop-brand-identity",
    "createdAt": "2025-11-03T10:22:00",
    "updatedAt": "2026-02-14T08:45:00"
  }
]
​
id
number
required
Project ID. Shares the same value as the linked item’s ID.
​
blocks
string
required
JSON array of content blocks. Each block object defines a type (e.g., image, text) and its associated properties. Stored as a LONGTEXT column.
​
background
string
Background color or image value for the project page.
​
blockGap
number
Vertical spacing (in pixels) between content blocks.
​
likes
number
Total number of likes the project has received.
​
views
number
Total number of times the project page has been viewed.
​
comments
number
Total number of comments on the project.
​
published
boolean
required
Whether the project is publicly visible. Only projects with published: true appear in public listings.
​
slug
string
required
URL-friendly unique identifier for the project. Used to link directly to a project page (e.g., /projects/coffee-shop-brand-identity). Must be unique across all projects.
​
createdAt
string
ISO 8601 datetime when the project was created.
​
updatedAt
string
ISO 8601 datetime when the project was last updated.

​
Get project by ID

GET /item-projects/{id} Returns a single project by its ID. Public endpoint.
​
id
number
required
The numeric ID of the project to retrieve.
curl -X GET http://localhost:8084/item-projects/10
You can also retrieve a project by its slug on the frontend. The slug field is useful for constructing human-readable URLs such as /projects/coffee-shop-brand-identity.

​
Create a project

POST /item-projects/register Creates a new project record. Requires authentication.
​
id
number
required
The item ID this project belongs to. Must reference an existing item.
​
blocks
string
JSON-encoded array of content blocks. Each block should include a type field and any type-specific properties. Defaults to an empty array if omitted.
​
background
string
Background color (hex or CSS value) or image URL for the project page.
​
blockGap
number
Pixel spacing between content blocks.
​
published
boolean
default:"false"
Set to true to make the project publicly visible immediately. Defaults to false (draft).
​
slug
string
required
Unique URL-friendly identifier for the project. Use lowercase letters, numbers, and hyphens only (e.g., coffee-shop-brand-identity).
curl -X POST http://localhost:8084/item-projects/register \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 10,
    "blocks": "[{\"type\":\"image\",\"url\":\"https://cdn.example.com/work/cover.jpg\"},{\"type\":\"text\",\"content\":\"A brand identity project.\"}]",
    "background": "#F5F5F0",
    "blockGap": 24,
    "published": false,
    "slug": "coffee-shop-brand-identity"
  }'
The slug must be unique. If another project already uses the same slug, the request will fail.
Response 
{
  "id": 10,
  "blocks": "[{\"type\":\"image\",\"url\":\"https://cdn.example.com/work/cover.jpg\"},{\"type\":\"text\",\"content\":\"A brand identity project.\"}]",
  "background": "#F5F5F0",
  "blockGap": 24,
  "likes": 0,
  "views": 0,
  "comments": 0,
  "published": false,
  "slug": "coffee-shop-brand-identity",
  "createdAt": "2026-05-16T09:00:00",
  "updatedAt": "2026-05-16T09:00:00"
}

​
Update a project

PUT /item-projects/{id} Updates an existing project. Requires authentication. Use this endpoint to edit content blocks, change the background, or publish/unpublish the project.
​
id
number
required
The numeric ID of the project to update.
​
blocks
string
Updated JSON array of content blocks.
​
background
string
Updated background value.
​
blockGap
number
Updated block spacing in pixels.
​
published
boolean
Set to true to publish the project, or false to revert it to draft status.
​
slug
string
Updated slug. Must remain unique across all projects.
curl -X PUT http://localhost:8084/item-projects/10 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"published": true}'
Setting published to true makes the project visible to anyone browsing the ECHO marketplace. Draft projects (published: false) are only accessible by the creator.

​
Get projects by creator

GET /item-projects/by-creator/{creatorId} Returns all projects belonging to a specific creator. Public endpoint.
​
creatorId
number
required
The numeric ID of the creator whose projects to retrieve.
curl -X GET http://localhost:8084/item-projects/by-creator/42

​
Increment view count

POST /item-projects/{id}/views Increments the project’s view counter by one and returns the updated project. No authentication required.
​
id
number
required
The numeric ID of the project.
curl -X POST http://localhost:8084/item-projects/10/views

​
Toggle like

POST /item-projects/{id}/likes Toggles the authenticated user’s like on a project. If the user has not liked the project, it adds a like. If they have already liked it, it removes the like. Requires authentication.
​
id
number
required
The numeric ID of the project to like or unlike.
curl -X POST http://localhost:8084/item-projects/10/likes \
  -H "Authorization: Bearer <token>"

​
Check like status

GET /item-projects/{id}/likes/status Returns whether the authenticated user has liked a project. Returns {"liked": false} for unauthenticated requests.
​
id
number
required
The numeric ID of the project.
curl -X GET http://localhost:8084/item-projects/10/likes/status \
  -H "Authorization: Bearer <token>"
Response: {"liked": true}

​
Get comments

GET /item-projects/{id}/comments Returns all comments on a project. Public endpoint.
​
id
number
required
The numeric ID of the project.
curl -X GET http://localhost:8084/item-projects/10/comments

​
Add a comment

POST /item-projects/{id}/comments Adds a comment to a project. Requires authentication.
​
id
number
required
The numeric ID of the project.
​
comment
string
required
The comment text to add.
curl -X POST http://localhost:8084/item-projects/10/comments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Stunning work — the color palette is spot on."}'

​
Delete a comment

DELETE /item-projects/{projectId}/comments/{commentId} Removes a comment from a project. Requires authentication. Only the comment author can delete their own comment.
​
projectId
number
required
The numeric ID of the project.
​
commentId
number
required
The numeric ID of the comment to delete.
curl -X DELETE http://localhost:8084/item-projects/10/comments/7 \
  -H "Authorization: Bearer <token>"

​
Delete a project

DELETE /item-projects/{id} Permanently removes a project record. Requires authentication.
​
id
number
required
The numeric ID of the project to delete.
Deleting a project is irreversible. All block content, engagement counters (likes, views, comments), and the slug will be permanently removed.
curl -X DELETE http://localhost:8084/item-projects/10 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us