Tags Endpoints
Organize memories with tags for easier discovery and filtering.
Add Tags to Memory
Add one or more tags to a memory.
Headers
| Header | Required | Description |
|---|---|---|
Authorization |
Yes | Bearer YOUR_JWT_TOKEN |
Content-Type |
Yes | application/json |
Path Parameters
| Parameter | Type | Description |
|---|---|---|
memory_id |
UUID | Memory identifier |
Request Body
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
tags |
array | Yes | Tags to add (max 10 total per memory) |
Tag Normalization
Tags are automatically normalized:
- Converted to lowercase
- Spaces and underscores replaced with hyphens
- Every character other than a-z, 0-9 and - is removed
| Input | Normalized |
|---|---|
"Python" |
"python" |
"Best Practices" |
"best-practices" |
"async_await" |
"async-await" |
"project:alpha" |
"projectalpha" |
A tag can be up to 50 characters long. See Tag Limits.
Response
{
"status": "success",
"data": {
"memory_id": "550e8400-e29b-41d4-a716-446655440000",
"tags": ["async", "best-practices", "python"],
"warnings": null
},
"meta": {...}
}
Response Fields
| Field | Description |
|---|---|
memory_id |
The memory identifier |
tags |
Complete list of tags now on the memory, in alphabetical order |
warnings |
null, or an array with one object for each tag that was not stored |
When a tag is not stored, the other tags in the request are still added and the response says which one was dropped:
{
"memory_id": "550e8400-e29b-41d4-a716-446655440000",
"tags": ["async", "async-await", "best-practices", "python"],
"warnings": [
{
"original": "x",
"normalized": null,
"reason": "Tag 'x' normalized to empty string"
}
]
}
Errors
| Status | Code | Description |
|---|---|---|
| 400 | VAL_VALIDATION_FAILED |
The memory would have more than 10 tags (Memory would have 12 tags, exceeding maximum of 10 tags) |
| 400 | VAL_VALIDATION_FAILED |
None of the tags in the request is valid (All provided tags were invalid) |
| 403 | AUTH_INSUFFICIENT_PERMISSIONS |
The token does not have the write scope |
| 404 | RES_NOT_FOUND |
Memory not found |
| 422 | VAL_VALIDATION_FAILED |
The request body is not valid |
Remove Tags from Memory
Remove specific tags from a memory.
Request Body
Response
{
"status": "success",
"data": {
"memory_id": "550e8400-e29b-41d4-a716-446655440000",
"tags": ["async", "python"],
"warnings": null
},
"meta": {...}
}
Response Fields
| Field | Description |
|---|---|
memory_id |
The memory identifier |
tags |
Remaining tags after removal |
warnings |
null, or an array of warning objects (same shape as in Add Tags) |
Removing a tag needs the write scope, not delete. Asking to remove a tag the memory does not have is not an error.
Get Memory Tags
Get all tags for a specific memory.
Response
Returns an array of tag names. Empty array if the memory has no tags.
List All Tags
List all tags with usage counts.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer | 1 |
Page number (minimum 1) |
per_page |
integer | 50 |
Tags per page (1-100) |
Response
{
"status": "success",
"data": {
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "python",
"usage_count": 45,
"created_at": "2026-01-01T00:00:00.038771Z"
},
{
"id": "660f9500-f30c-52e5-b827-557766551111",
"name": "javascript",
"usage_count": 32,
"created_at": "2026-01-02T00:00:00.723359Z"
},
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"name": "machine-learning",
"usage_count": 28,
"created_at": "2026-01-03T00:00:00.112233Z"
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 156,
"pages": 4,
"has_next": true,
"has_prev": false
}
},
"meta": {...}
}
Notes
- Tags are sorted by usage count (most used first)
usage_countshows how many memories use each tag- Tags with zero usage may be cleaned up periodically
Get Memories by Tag
Get all memories with a specific tag (paginated).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
tag |
string | Tag name (normalized) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer | 1 |
Page number (minimum 1) |
per_page |
integer | 20 |
Results per page (1-100) |
Response
{
"status": "success",
"data": {
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "Python async programming uses asyncio...",
"memory_type": "fact",
"importance": 0.8,
"confidence": 0.8,
"created_at": "2026-01-01T00:00:00.288284Z",
"tags": ["async", "python"],
...
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 45,
"pages": 3,
"has_next": true,
"has_prev": false
}
},
"meta": {...}
}
Response Fields
| Field | Description |
|---|---|
items |
Array of Memory objects with the specified tag |
pagination |
Pagination metadata (page, per_page, total, pages, has_next, has_prev) |
Notes
- Tag name is normalized before matching (lowercase, hyphens)
- Returns empty results (
items: [],total: 0) for non-existent tags - Memories are returned with full Memory schema
- Use pagination for large result sets
Example
# Get first 10 memories tagged with "python"
curl -X GET "https://api.penfield.app/api/v2/tags/python/memories?page=1&per_page=10" \
-H "Authorization: Bearer $JWT_TOKEN"
# Get second page
curl -X GET "https://api.penfield.app/api/v2/tags/python/memories?page=2&per_page=10" \
-H "Authorization: Bearer $JWT_TOKEN"
Filtering Memories by Tags
Alternative: Use the memories list endpoint to filter by multiple tags:
Tag Filter Behavior
- Multiple tags use OR logic (memories matching ANY tag)
- Tags are normalized before matching
- Case-insensitive matching
Example
# Get memories tagged with either "python" or "javascript"
curl -X GET "https://api.penfield.app/api/v2/memories?tags=python,javascript" \
-H "Authorization: Bearer $JWT_TOKEN"
Best Practices
Tag Naming
- Use lowercase and hyphens:
machine-learningnotMachine Learning - Be consistent: decide between
mlandmachine-learning - Use hierarchical tags:
python-async,python-testing - Avoid overly specific tags:
my-project-v2-feature-x
Tag Organization
| Category | Example Tags |
|---|---|
| Language | python, javascript, rust |
| Topic | machine-learning, web-dev, devops |
| Type | tutorial, reference, snippet |
| Status | verified, needs-review, deprecated |
| Project | project-alpha, project-beta |
Tag Limits
| Limit | Value |
|---|---|
| Max tags per memory | 10 |
| Max tag length | 50 characters |
| Allowed characters | a-z, 0-9, - |
A tag that is not valid is not stored. Add Tags reports each tag it did not store in warnings, and returns 400 when none of the tags in the request is valid.