Projects API

Create, update, and manage projects

1 min read

Project lifecycle management. Create projects with name and description, update settings, control visibility and status, and handle project deletion. Supports pagination and search for listing projects.

Available Endpoints

Method	Endpoint	Description
`GET`	`/api/user/organizations/{organizationId}/projects`	List organization projects
`POST`	`/api/user/organizations/{organizationId}/projects`	Create a new project
`GET`	`/api/user/organizations/{organizationId}/projects/{id}`	Get a specific project
`PUT`	`/api/user/organizations/{organizationId}/projects/{id}`	Update a project (manual edit)
`DELETE`	`/api/user/organizations/{organizationId}/projects/{id}`	Delete a project

Endpoints

GET

/api/user/organizations/{organizationId}/projects

List organization projects

Get a paginated list of projects owned by the organization.

Bearer Token•Scopes: projects:read, organization:read

Request

curl -X GET "http://localhost:3030/api/user/organizations/{organizationId}/projects" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"

const response = await fetch("http://localhost:3030/api/user/organizations/{organizationId}/projects", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);

Path Parameters

Name	Type	Description
`organizationId`required	string	Organization ID `550e8400-e29b-41d4-a716-446655440000`

Query Parameters

Name	Type	Description
`offset`	integer,null	Number of items to skip `0`
`limit`	number	Number of items to return (max 100) `20`
`q`	string	Search query (matches name)

Response 200

Projects retrieved successfully

{
"success": true,
"status": 200,
"code": "OK",
"message": "Items fetched successfully",
"data": [
  {
    "id": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "createdByUserId": "string",
    "name": "string",
    "description": "string",
    "businessContext": "string",
    "status": "draft",
    "frequency": "weekly",
    "timezone": "string",
    "topics": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "watchFor": "string",
        "sources": [
          {}
        ]
      }
    ],
    "lastRunAt": {},
    "nextRunAt": {},
    "createdByUser": {
      "id": "507f1f77bcf86cd799439012",
      "fullName": "John Doe"
    }
  }
],
"meta": {
  "total": 100,
  "offset": 0,
  "limit": 10,
  "hasMore": true
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

POST

/api/user/organizations/{organizationId}/projects

Create a new project

Create a project. The server uses `monitoringIntent` and `businessContext` to generate research topics via LLM. Topics are returned on the response.

Bearer Token•Scopes: projects:write, organization:read

Request

curl -X POST "http://localhost:3030/api/user/organizations/{organizationId}/projects" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"name":"Fintech competitor watch","monitoringIntent":"Track pricing and feature changes from Stripe, Adyen, and Mollie. Flag anything affecting our SMB tier.","businessContext":"EU-based B2B payments platform serving SMBs. Compete on price and onboarding speed.","description":"string"}'

const response = await fetch("http://localhost:3030/api/user/organizations/{organizationId}/projects", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "name": "Fintech competitor watch",
  "monitoringIntent": "Track pricing and feature changes from Stripe, Adyen, and Mollie. Flag anything affecting our SMB tier.",
  "businessContext": "EU-based B2B payments platform serving SMBs. Compete on price and onboarding speed.",
  "description": "string"
}),
});

const data = await response.json();
console.log(data);

Path Parameters

Name	Type	Description
`organizationId`required	string	Organization ID `550e8400-e29b-41d4-a716-446655440000`

Body Parameters

Name	Type	Description
`name`required	string	`Fintech competitor watch`
`monitoringIntent`required	string	What do you want to monitor? Used once at intake to generate topics; not stored. `Track pricing and feature changes from Stripe, Adyen, and Mollie. Flag anything affecting our SMB tier.`
`businessContext`	string	Long-lived context the AI should know about your business. `EU-based B2B payments platform serving SMBs. Compete on price and onboarding speed.`
`description`	string

Response 201

Project created successfully

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "createdByUserId": "string",
  "name": "string",
  "description": "string",
  "businessContext": "string",
  "status": "draft",
  "frequency": "weekly",
  "timezone": "string",
  "topics": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "watchFor": "string",
      "sources": [
        {
          "url": {},
          "lastContentHash": {},
          "lastFetchedAt": {}
        }
      ]
    }
  ],
  "lastRunAt": {},
  "nextRunAt": {},
  "createdByUser": {
    "id": "507f1f77bcf86cd799439012",
    "fullName": "John Doe"
  }
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

GET

/api/user/organizations/{organizationId}/projects/{id}

Get a specific project

Bearer Token•Scopes: projects:read, organization:read

Request

curl -X GET "http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"

const response = await fetch("http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);

Path Parameters

Name	Type	Description
`organizationId`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`
`id`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`

Response 200

Project retrieved successfully

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "createdByUserId": "string",
  "name": "string",
  "description": "string",
  "businessContext": "string",
  "status": "draft",
  "frequency": "weekly",
  "timezone": "string",
  "topics": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "watchFor": "string",
      "sources": [
        {
          "url": {},
          "lastContentHash": {},
          "lastFetchedAt": {}
        }
      ]
    }
  ],
  "lastRunAt": {},
  "nextRunAt": {},
  "createdByUser": {
    "id": "507f1f77bcf86cd799439012",
    "fullName": "John Doe"
  }
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

PUT

/api/user/organizations/{organizationId}/projects/{id}

Update a project (manual edit)

Update an existing project. All fields optional. `topics` (when present) replaces the full list; per-source state is preserved for stable topic ids.

Bearer Token•Scopes: projects:write, organization:read

Request

curl -X PUT "http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"name":"string","description":{},"businessContext":{},"status":"draft","frequency":"weekly","timezone":"string","topics":[{"id":"string","name":"string","description":"string","watchFor":"string","sources":[{"url":"string"}]}]}'

const response = await fetch("http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}", {
method: "PUT",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "name": "string",
  "description": {},
  "businessContext": {},
  "status": "draft",
  "frequency": "weekly",
  "timezone": "string",
  "topics": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "watchFor": "string",
      "sources": [
        {
          "url": "string"
        }
      ]
    }
  ]
}),
});

const data = await response.json();
console.log(data);

Path Parameters

Name	Type	Description
`organizationId`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`
`id`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`

Body Parameters

Name	Type	Description
`name`	string
`description`	string,null
`businessContext`	string,null
`status`	string
`frequency`	string
`timezone`	string
`topics`	UpdateTopic[]

Response 200

Project updated successfully

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "createdByUserId": "string",
  "name": "string",
  "description": "string",
  "businessContext": "string",
  "status": "draft",
  "frequency": "weekly",
  "timezone": "string",
  "topics": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "watchFor": "string",
      "sources": [
        {
          "url": {},
          "lastContentHash": {},
          "lastFetchedAt": {}
        }
      ]
    }
  ],
  "lastRunAt": {},
  "nextRunAt": {},
  "createdByUser": {
    "id": "507f1f77bcf86cd799439012",
    "fullName": "John Doe"
  }
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

DELETE

/api/user/organizations/{organizationId}/projects/{id}

Delete a project

Bearer Token•Scopes: projects:write, organization:read

Request

curl -X DELETE "http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"

const response = await fetch("http://localhost:3030/api/user/organizations/{organizationId}/projects/{id}", {
method: "DELETE",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);

Path Parameters

Name	Type	Description
`organizationId`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`
`id`required	string	UUID identifier `550e8400-e29b-41d4-a716-446655440000`

Response 200

Project deleted successfully

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "createdByUserId": "string",
  "name": "string",
  "description": "string",
  "businessContext": "string",
  "status": "draft",
  "frequency": "weekly",
  "timezone": "string",
  "topics": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "watchFor": "string",
      "sources": [
        {
          "url": {},
          "lastContentHash": {},
          "lastFetchedAt": {}
        }
      ]
    }
  ],
  "lastRunAt": {},
  "nextRunAt": {},
  "createdByUser": {
    "id": "507f1f77bcf86cd799439012",
    "fullName": "John Doe"
  }
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

Payments API

User API