Tags

Tags categorize and filter ideas. Each tag has a name, an optional colour, and — on the list endpoint — a count of ideas using it. Tag names are unique per account, and tags are created implicitly whenever you attach an unknown name to an idea.

List Tags

GET /api/v1/tags

Returns every tag on the account, most-used first, then alphabetically. There is no pagination.

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,
      "user_id": "3f2a91c47b0e4d5aa8c61e0f2b7d4c93",
      "name": "feature-request",
      "color": "#4f46e5",
      "vectorize_id": "tag_1",
      "created_at": "2026-02-01 09:00:00",
      "idea_count": 12
    },
    {
      "id": 2,
      "user_id": "3f2a91c47b0e4d5aa8c61e0f2b7d4c93",
      "name": "bug",
      "color": null,
      "vectorize_id": null,
      "created_at": "2026-02-03 11:20:00",
      "idea_count": 5
    }
  ]
}

idea_count counts unarchived ideas only, so archiving ideas lowers it and a tag can sit at zero without being deleted. vectorize_id is null until the tag’s embedding is generated in the background — until then it cannot appear in similarity results.

Find Similar Tags

GET /api/v1/tags/similar

Finds tags whose embeddings are close to a given tag’s. Useful for spotting near-duplicate tags (ui vs frontend) before they fragment your organization.

Query Parameters

Parameter	Type	Required	Description
tag	string	Yes	Tag name (not id) to compare against
limit	number	No	Max results (default 5, clamped to 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 }
  ]
}

Situation	Response
Tag name not found on your account	404 { "error": "Tag \"frontend\" not found" }
Tag exists but has no embedding yet	200 { "similar": [], "message": "Tag has no embedding yet" }
tag parameter omitted	400 { "error": "Missing \"tag\" query parameter" }

There is no score floor — every neighbour the index returns is listed, so a small account with unrelated tags still gets results with low similarity values. Judge by the number, not by presence in the list.

Create Tag

POST /api/v1/tags

Request Body

Field	Type	Required	Description
name	string	Yes	1–50 characters, unique within your account
color	string	No	Hex colour, exactly #rrggbb (six digits, #f00 is rejected)

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,
    "user_id": "3f2a91c47b0e4d5aa8c61e0f2b7d4c93",
    "name": "backend",
    "color": "#059669",
    "vectorize_id": null,
    "created_at": "2026-03-24 09:00:00"
  }
}

Creating a tag that already exists returns 409 { "error": "Tag name already exists" }. You rarely need this endpoint — attaching an unknown tag name to an idea creates it for you.

Update Tag

PATCH /api/v1/tags/:id

Update the name, colour, or both. Only provided fields change. Takes the tag id, not its name.

Request Body

Field	Type	Required	Description
name	string	No	1–50 characters
color	string	No	Hex colour 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,
    "user_id": "3f2a91c47b0e4d5aa8c61e0f2b7d4c93",
    "name": "backend",
    "color": "#0ea5e9",
    "vectorize_id": null,
    "created_at": "2026-03-24 09:00:00"
  }
}

Renaming onto an existing name fails with a 500

The uniqueness conflict that POST reports as a clean 409 is not caught here: renaming tag backend to a name you already use returns 500 { "error": "Internal server error" } and changes nothing. Check the tag list first, and treat a 500 from this endpoint as a name collision rather than an outage. To combine two tags, retag the ideas and delete the empty one.

Renaming a tag does not re-embed it, so GET /tags/similar keeps comparing against the old name’s embedding until the tag is re-embedded in the background.

Delete Tag

DELETE /api/v1/tags/:id

Deletes the tag and detaches it from every idea. The ideas themselves are untouched — no bodies, statuses, or other tags change.

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

Response 200 OK

{
  "success": true
}

Deleting a tag that is not yours or does not exist returns 404. There is no undo — recreating the tag does not restore its associations.

Unused tags are deleted for you

Every write that sets an idea’s tags — POST /ideas, PATCH /ideas/:id with tags, and the bulk endpoint — finishes by deleting all of your tags that are attached to no idea. A tag you created here and have not used yet will disappear the next time any idea’s tags are replaced, taking its colour with it. Create tags by attaching them, not ahead of time.

Tag Schema

Field	Type	Description
id	number	Unique tag identifier
user_id	string	Owning account
name	string	Display name, unique per account
color	string | null	Hex colour code
vectorize_id	string | null	Embedding id; null until the tag has been embedded
created_at	string	UTC YYYY-MM-DD HH:MM:SS
idea_count	number	Unarchived ideas using this tag — list endpoint only

Status Codes

Status	Meaning
200 OK	Successful read, update, or delete
201 Created	Tag created
400 Bad Request	Validation error (name length, colour format, non-numeric id, missing tag param)
401 Unauthorized	Missing or invalid auth
404 Not Found	Tag not found, or not yours
409 Conflict	POST only — a tag with that name already exists
500 Internal Server Error	PATCH only — the new name collides with an existing tag

Next Steps

Ideas Attach tags at capture time, replace them wholesale, or add and remove them in bulk.

Tag concepts Auto-tagging, tag hygiene, and when merging two tags is worth the effort.

Search Filtering by tag versus searching by meaning — and when each one finds more.

Error Handling What each status code means across the whole API.