Recent Searches - Huddle/huddle-apis GitHub Wiki

Summary

The Recent Searches API allows users to manage their search history within the Huddle platform. This API provides functionality to retrieve and store recent search queries, enabling a personalized search experience with quick access to frequently used search terms.

Table of Contents

Retrieve Recent Searches

Endpoint

GET /users/{userId}/recentsearches

Request Example

GET /files/users/{userId}/recentsearches HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: OAuth2 <access_token>

Response Example

{
  "links": [
    {
      "rel": "self",
      "href": "https://my.huddle.dev/apigateway/files/users/123/recentsearches"
    }
  ],
  "maxItems": 5,
  "items": [
    {
      "search": "huddle_5",
      "links": [
        {
          "rel": "delete",
          "href": "https://my.huddle.dev/apigateway/files/users/123/recentsearches/10243"
        },
        {
          "rel": "self",
          "href": "https://my.huddle.dev/apigateway/files/users/123/recentsearches/10243"
        }
      ],
      "addedDate": "Fri, 22 Aug 2025 10:03:23 GMT",
      "isPinned": false
    },
    {
      // Other recent search
    }
  ]
}

Response Parameters

Parameter Type Required Description
search string Yes Search term.
links object Yes Related link include self, delete link.
addedDate date Yes The date of the search refers to the timestamp when the keyword was queried.
isPinned string Yes Recent searches are preserved and cannot be deleted.
maxItems string Yes The maximum number of recent search items that can be stored.

Store Recent Searches

Endpoint

POST /users/{userId}/recentsearches

Store Request Example

POST /files/users/{userId}/recentsearches HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: OAuth2 <access_token>
{
    "search": "huddle_1"
}

Store Response

HTTP/1.1 201 Created
Content-Type: application/json
Date: Fri, 23 Aug 2013 09:23:33 GMT

Error Handling

The API returns standard HTTP status codes:

Status Code Description
200 OK Request successful
201 Created Recent search successfully stored
204 No Content Recent search successfully deleted
400 Bad Request Invalid parameters (e.g., empty search term, search term too long)
401 Unauthorized Missing or invalid authentication token
403 Forbidden User does not have permission to access this resource
404 Not Found User or search entry does not exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Best Practices

Search Term Management

  1. Normalize Search Terms: Trim whitespace and convert to lowercase before storing to prevent duplicates
  2. Character Limits: Keep search terms under 255 characters for optimal performance