Tags

Tags let you categorize and filter ideas. Each tag has a name, an optional color, and a count of associated ideas.

List Tags

GET /api/v1/tags

Returns all tags for the authenticated user, including the number of ideas associated with each tag.

curl

curl https://neuralrepo.com/api/v1/tags \
  -H "X-API-Key: nrp_YOUR_KEY"

JavaScript

const res = await fetch("https://neuralrepo.com/api/v1/tags", {
  headers: { "X-API-Key": "nrp_YOUR_KEY" },
});
const tags = await res.json();

Response 200 OK

{
  "tags": [
    {
      "id": 1,
      "name": "feature-request",
      "color": "#4f46e5",
      "idea_count": 12
    },
    {
      "id": 2,
      "name": "bug",
      "color": "#dc2626",
      "idea_count": 5
    }
  ]
}

Find Similar Tags

GET /api/v1/tags/similar

Find semantically similar tags using vector embeddings.

Query Parameters

Parameter	Type	Required	Description
tag	string	Yes	Tag name to find similar tags for
limit	number	No	Max results (default 5, max 20)

curl

curl "https://neuralrepo.com/api/v1/tags/similar?tag=frontend&limit=5" \
  -H "X-API-Key: nrp_YOUR_KEY"

Response 200 OK

{
  "similar": [
    { "name": "ui", "idea_count": 8, "similarity": 0.82 },
    { "name": "react", "idea_count": 5, "similarity": 0.76 },
    { "name": "css", "idea_count": 3, "similarity": 0.71 }
  ]
}

If the tag has no embedding yet, the response includes "message": "Tag has no embedding yet".

Create Tag

POST /api/v1/tags

Request Body

Field	Type	Required	Description
name	string	Yes	1-50 characters, must be unique
color	string	No	Hex color in #rrggbb format

curl

curl -X POST https://neuralrepo.com/api/v1/tags \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "backend", "color": "#059669"}'

JavaScript

const res = await fetch("https://neuralrepo.com/api/v1/tags", {
  method: "POST",
  headers: {
    "X-API-Key": "nrp_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "backend", color: "#059669" }),
});
const tag = await res.json();

Response 201 Created

{
  "tag": {
    "id": 3,
    "name": "backend",
    "color": "#059669",
    "created_at": "2026-03-24T09:00:00Z"
  }
}

Update Tag

PATCH /api/v1/tags/:id

Update the name, color, or both. Only provided fields are changed.

Request Body

Field	Type	Required	Description
name	string	No	1-50 characters
color	string	No	Hex color in #rrggbb format

curl -X PATCH https://neuralrepo.com/api/v1/tags/3 \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color": "#0ea5e9"}'

Response 200 OK

{
  "tag": {
    "id": 3,
    "name": "backend",
    "color": "#0ea5e9"
  }
}

Delete Tag

DELETE /api/v1/tags/:id

Removes the tag. Ideas that had this tag will have it detached but are not otherwise affected.

curl -X DELETE https://neuralrepo.com/api/v1/tags/3 \
  -H "X-API-Key: nrp_YOUR_KEY"

Response 200 OK

{
  "success": true
}

Tag Schema

Field	Type	Description
id	number	Unique tag identifier
name	string	Display name
color	string | null	Hex color code
idea_count	number	Number of ideas using this tag

Status Codes

Status	Meaning
200 OK	Successful read, update, or delete
201 Created	Tag created
400 Bad Request	Validation error (name too long, invalid color)
401 Unauthorized	Missing or invalid auth
404 Not Found	Tag not found
409 Conflict	Tag with that name already exists