Summary

The Recent Searches API lets a user read and update their recent search history in Huddle. It is exposed on the Files API (public paths are under /files/).

Operations

Method	Path	Purpose	Details
GET	/files/users/{userId}/recentsearches	Retrieve recent searches	Jump
POST	/files/users/{userId}/recentsearches	Create a recent search	Jump
DELETE	/files/users/123/recentsearches/10243	Delete a recent search	Jump

---

Retrieve recent searches

Request

Method	Path
GET	/files/users/{userId}/recentsearches

The {userId} in the path must match the authenticated user; otherwise the API returns 403 Forbidden.

Request example

GET /files/users/{userId}/recentsearches HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response example

The collection includes a self link. Each item includes the search text, when it was added, whether it is pinned, and the search type. The list response does not include per-item links or a separate identifier field in the JSON view; use the Location header from a successful POST when you need the URI for a specific entry.

{
  "links": [
    {
      "rel": "self",
      "href": "https://my.huddle.dev/apigateway/files/users/123/recentsearches"
    }
  ],
  "maxItems": 5,
  "items": [
    {
      "search": "project timeline",
      "addedDate": "2025-08-22T10:03:23Z",
      "isPinned": false
    },
    {
      "search": "design",
      "addedDate": "2025-08-21T14:00:00Z",
      "isPinned": true
    }
  ]
}

Response parameters

Parameter	Type	Required	Description
links	array	Yes	Includes rel: "self" for the collection.
maxItems	number	Yes	Configured maximum number of recent searches stored for a user.
items	array	Yes	Recent search entries (newest first in typical usage).
search	string	Yes	Search text or tag value.
addedDate	string	Yes	When the entry was recorded (ISO 8601 in JSON).
isPinned	boolean	Yes	When true, the entry is treated as pinned in the product model.
searchType	string	Yes	SearchTerm or Tag (see Create a recent search).

---

Create a recent search

Request

Method	Path
POST	/files/users/{userId}/recentsearches

Create request example

POST /files/users/{userId}/recentsearches HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "search": "project timeline"
}

Create response

201 Created with a Location header pointing at the new resource, for example:

HTTP/1.1 201 Created
Location: https://my.huddle.dev/apigateway/files/users/123/recentsearches/10243

---

Delete a recent search

Request

Method	Path
DELETE	/files/users/{userId}/recentsearches/{recentSearchId}

Delete request example

DELETE /files/users/123/recentsearches/10243 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Use the recentSearchId from the Location header returned when the entry was created, or from your client’s own tracking if your integration already stores it.

Delete response

204 No Content on success.

---

Error handling

Status code	When it applies
200 OK	GET succeeded; body is the recent searches collection (possibly empty).
201 Created	POST succeeded; Location identifies the new entry.
204 No Content	DELETE succeeded.
304 Not Modified	Backing store (e.g. Redis) unavailable; handler returns this instead of failing the call in some paths.
400 Bad Request	Invalid body: missing/invalid searchType, empty or overlong search, or validation failure on the command.
401 Unauthorized	Missing or invalid token (typical gateway / auth behaviour).
403 Forbidden	{userId} does not match the authenticated user.
500 Internal Server Error	Unexpected server error.

---

Best practices

1. Respect length limits — Keep search between 1 and 255 characters after trimming meaningful input on the client if you want to avoid 400.
2. Persist the created URI when needed — If you need to delete an entry later, retain the id from the Location header on 201, since the list payload does not expose a separate id field in the public view model.