Tags API

Manage tags for organizing nodes and files.

Endpoints

POST /tags

POST Create a new tag.

curl -X POST "https://api.ofself.ai/api/v1/tags" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work",
    "color": "#3B82F6"
  }'

Request Body:

Field	Type	Required	Description
name	string	Yes	Tag name (1-100 characters)
color	string	No	Hex color code (#RRGGBB)
category	string	No	Category (e.g., topic, person, location)
description	string	No	Tag description
parent_tag_id	UUID	No	Parent tag for hierarchical tags

Response: 201 Created

{
  "id": "tag_work123",
  "name": "Work",
  "color": "#3B82F6",
  "owner_id": "user-123",
  "created_at": "2024-01-15T10:30:00Z"
}

---

GET /tags

GET List all tags.

curl -X GET "https://api.ofself.ai/api/v1/tags" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

Query Parameters:

Parameter	Type	Description
search	string	Search tag names
category	string	Filter by category
parent_tag_id	UUID	Filter by parent tag
access	string	owned, shared, or all (default)
include_nodes	boolean	Include associated nodes (default: false)
view	string	Graph view filter: identity (default) or neutral
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 50, max: 200)

---

GET /tags/:tag_id

GET Get a single tag.

curl -X GET "https://api.ofself.ai/api/v1/tags/tag_work" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

---

PUT /tags/:tag_id

PUT Update a tag.

curl -X PUT "https://api.ofself.ai/api/v1/tags/tag_work" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Projects",
    "color": "#22C55E"
  }'

---

DELETE /tags/:tag_id

DELETE Delete a tag.

curl -X DELETE "https://api.ofself.ai/api/v1/tags/tag_work" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

Note: This removes the tag but doesn't delete nodes with this tag.

---

POST /tags/bulk-delete

POST Delete multiple tags at once.

curl -X POST "https://api.ofself.ai/api/v1/tags/bulk-delete" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": ["tag-uuid-1", "tag-uuid-2", "tag-uuid-3"]
  }'

Request Body:

Field	Type	Required	Description
tag_ids	array	Yes	Array of tag UUIDs to delete

Response: 200 OK

{
  "deleted_count": 2,
  "not_found_ids": ["tag-uuid-3"],
  "message": "Successfully deleted 2 tag(s)"
}

---

GET /tags/:tag_id/nodes

GET Get all nodes with a specific tag.

curl -X GET "https://api.ofself.ai/api/v1/tags/tag_work/nodes" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

---

GET /tags/:tag_id/files

GET Get all files with a specific tag.

curl -X GET "https://api.ofself.ai/api/v1/tags/tag_work/files" \
  -H "X-API-Key: your-key" \
  -H "X-User-ID: user-123"

---

Third-Party Tag Creation

POST /third-party/tags

POST Create a tag on behalf of a user. Requires the app to have tags.create or tags.write permission.

curl -X POST "https://api.ofself.ai/api/v1/third-party/tags" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quarterly-review",
    "category": "business",
    "color": "#3498db",
    "description": "Quarterly review documents"
  }'

Request Body:

Field	Type	Required	Description
name	string	Yes	Tag name
category	string	No	Tag category
color	string	No	Hex color code
description	string	No	Tag description

Response: 201 Created

No X-User-ID Header

This endpoint derives the user from the API key's authorization. The X-User-ID header is not needed.

Errors:

• 403 PERMISSION_DENIED — App doesn't have tags.create or tags.write permission
• 409 — Tag with this name already exists for the user