Create Entity
Endpoint
URL: /:projectId/entities/
Method: POST
Authentication Required: Optional
Description
Creates a new entity. Can be used with or without authentication. When authenticated, author gains reputation.
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | No | Bearer token for authenticated users. |
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | No | Optional ID of the user creating the entity. Must match the authenticated user. |
foreignId | string | No | External reference ID. |
sourceId | string | No | Optional origin identifier. |
title | string | No | Title of the entity. |
content | string | No | Content body of the entity. |
attachments | array | No | Array of attachment objects. |
keywords | array | No | Array of keywords associated with the entity. |
mentions | array | No | List of mentioned users with { id: string } format. |
location | object | No | Location object { longitude: number, latitude: number }. |
metadata | object | No | Optional custom metadata object. |
excludeUserId | boolean | No | If true, excludes assigning a user ID. |
Example Request
{
"userId": "user_123",
"foreignId": "external_456",
"title": "Interesting Thought",
"content": "Here's something I've been thinking about...",
"mentions": [{ "id": "user_789", "username": "ben_322" }],
"location": { "longitude": -73.935242, "latitude": 40.73061 },
"metadata": { "mood": "reflective" }
}Response
Success Response (200 OK)
Returns the created and fully populated entity object:
{
"id": "entity_abc",
"userId": "user_123",
"shortId": "abc123",
"title": "Interesting Thought",
"content": "Here's something I've been thinking about...",
"mentions": [ { "id": "user_789", "username": "ben_322" } ],
...
}Error Responses
Unauthorized (403 Forbidden)
{
"error": "User is not authorized to create this entity.",
"code": "entity/unauthorized"
}Invalid Project ID (400 Bad Request)
{
"error": "Invalid projectId, project does not exist.",
"code": "report/invalid-foreign-key"
}Server Error (500 Internal Server Error)
{
"error": "Internal server error.",
"code": "entity/server-error",
"details": "<Error message>"
}Notes
- If
userIdis provided, it must match the logged-in user unless the request is from a master key. - Mentions will trigger a notification if the mentioned user is not the creator.
- User reputation is updated if an authenticated user creates the entity.