Search files or folders - Huddle/huddle-apis GitHub Wiki

Summary

The File Search API provides powerful search capabilities across documents and folders within your Huddle workspaces. Search through document content, metadata, and folder structures with advanced filtering options including date ranges and workspace-specific queries.

Table of Contents

Document Search

Search for documents across workspaces with comprehensive filtering and relevance scoring.

Endpoint

GET /search/documents

Document Request Example

GET /files/search/documents?query=huddle&workspaceids=1,2,3&updatedfrom=2017-01-01&updatedto=2017-01-02&createdfrom=2017-01-01&createdto=2017-01-02&includecontent=true&includetitle=true HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: OAuth2 <access_token>

Document Response Example

{
  "results": [
    {
      "score": 100.0,
      "document": {
        "title": "Huddle PopwerPoinr",
        "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "description": "",
        "extension": "pptx",
        "links": [
          {
            "rel": "content",
            "href": "https://files.huddle.f1/apigateway/files/documents/20296/content",
            "type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
            "title": "Huddle PopwerPoinr.pptx"
          },
          {
            // Other links
          }
        ],
        "actors": [
          {
            "name": "Jeffrey Lai",
            "email": "[email protected]",
            "rel": "owner",
            "links": [
              {
                "rel": "self",
                "href": "https://my.huddle.f1/apigateway/users/563"
              },
              {
                // Other links
              }
            ]
          },
          {
            "name": "Jeffrey Lai",
            "email": "[email protected]",
            "rel": "updated-by",
            "links": [
              {
                "rel": "self",
                "href": "https://my.huddle.f1/apigateway/users/563"
              },
              {
                // Other links
              }
            ]
          }
        ],
        "version": 1,
        "size": 29475,
        "updated": "Wed, 02 Jul 2025 08:41:52 GMT",
        "created": "Wed, 02 Jul 2025 08:41:52 GMT",
        "processingStatus": "Complete",
        "views": -1,
        "workspace": {
          "title": "Enhanced Search",
          "links": [
            {
              "rel": "self",
              "href": "https://my.huddle.f1/apigateway/workspaces/2032"
            },
            {
              // Other links
            }
          ],
          "downloadEnabled": true,
          "printEnabled": true
        },
        "publications": {
          "links": [],
          "scope": "none"
        },
        "tags": []
      }
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://my.huddle.f1/apigateway/files/search/documents?query=huddle&workspaceids=1,2,3&includecontent=true&pagesize=50&includetitle=true"
    }
  ]
}

Document Parameters

Parameter Type Mandatory Description
query string ✅ Yes The search term.
pagesize integer ❌ No Maximum number of results to return (1-100). Default: 100
workspaceids string ❌ No Comma-separated list of workspace IDs to search within. (Ex: 1,2,3)
updatedfrom date ❌ No Start date for last modified filter (ISO 8601 format). Ignored when updatedto is not provided.
updatedto date ❌ No End date for last modified filter (ISO 8601 format). Ignored when updatedfrom is not provided.
createdfrom date ❌ No Start date for creation date filter (ISO 8601 format). Ignored when createdTo is not provided.
createdto date ❌ No End date for creation date filter (ISO 8601 format). Ignored when createdFrom is not provided.
includetitle boolean ❌ No Include document title in search scope.
includecontent boolean ❌ No Include document content, description and tag in search scope.
nocache boolean ❌ No Bypasses cache for a fresh response. Default to false

Workspace Filtering

The workspaceids parameter is optional. When omitted, the search returns results from all workspaces the authenticated user has access to.

Best Practice: Always specify workspace IDs to improve performance and relevance of search results.

Example with workspace filtering:

GET /files/search/documents?query=something&workspaceids=1,3 HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Folder Search

Search for folders within workspaces with date range filtering.

Endpoint

GET /search/folders

Folder Request Example

GET /files/search/folders?query=something&workspaceids=1&updatedfrom=2017-01-01T12%3A02%3A02Z&updatedto=2017-01-02T12%3A02%3A02Z&createdfrom=2017-01-01T12%3A02%3A02Z&createdto=2017-01-02T12%3A02%3A02Z HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 <access_token>

Folder Response Example

<search>
    <link rel="self" href="..." />
    <results>
        <result> 
            <score>100</score>
            <folder title="something" description="folder description">
                <links rel="self" href="..." />
                <links rel="alternate" href="http://my.huddle.net/workspace/469/folders/123" type="text/html" />
                <actors name="document owner" email="[email protected]" rel="owner">
               		<links rel="self" href="https://..." />
               		<links rel="avatar" href="https://..." />
               		<links rel="alternate" href="https://..." type="text/html" />
                </actors>
		        <updated>Thu, 07 Feb 2013 12:12:58 GMT</updated>
        		<created>Thu, 06 Dec 2012 17:43:40 GMT</created>
        		<workspace title="workspace title">
        		        <links rel="self" href="https://..." />
	            </workspace>
            </folder>
        </result>
    </results>
</search>

Folder Parameters

Parameter Type Mandatory Description
query string ✅ Yes The search term.
pagesize integer ❌ No Maximum number of results to return (1-100). Default: 100
workspaceids string ❌ No Comma-separated list of workspace IDs to search within. (Ex: 1,2,3)
updatedfrom date ❌ No Start date for last modified filter (ISO 8601 format). Ignored when updatedto is not provided.
updatedto date ❌ No End date for last modified filter (ISO 8601 format). Ignored when updatedfrom is not provided.
createdfrom date ❌ No Start date for creation date filter (ISO 8601 format). Ignored when createdTo is not provided.
createdto date ❌ No End date for creation date filter (ISO 8601 format). Ignored when createdFrom is not provided.
nocache Boolean ❌ No Bypasses cache for a fresh response. Default to false.

Note: Similar to document search, the workspaceids parameter is optional. When not provided, search returns results from all accessible workspaces.

Response Format

Common Properties

Property Type Description
results array Collection of search results
score number Relevance score (0-100) indicating match quality
links array Hypermedia links for navigation and actions
isCached boolean Indicates if results were retrieved from cache

Link Relations

Common rel values in the links array:

Relation Description HTTP Methods
self Current resource URI GET
content Direct link to document content GET
parent Parent folder or workspace GET
edit Edit endpoint PUT, PATCH
delete Delete endpoint DELETE
share Sharing and permissions GET, POST
alternate Alternative representations (HTML, mobile) GET
version-history Document version history GET
comments Document comments GET, POST

Error Handling

The API returns standard HTTP status codes:

Status Code Description
200 OK Request successful
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Missing or invalid authentication token
403 Forbidden Insufficient permissions for the requested resource
404 Not Found Resource does not exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Best Practices

Performance Optimization

  1. Specify Workspace IDs: Always include workspaceids to narrow search scope and improve response times
  2. Use Appropriate Page Sizes: Start with smaller page sizes (20-50) for faster initial responses
  3. Leverage Caching: Omit nocache parameter unless fresh data is critical

Search Query Tips

  1. Use Specific Terms: More specific queries yield better relevance scores
  2. Combine Filters: Use date ranges with workspace filtering for precise results
  3. Enable Content Search Judiciously: Set includecontent=true only when searching document body text
  4. IncludeTitle & IncludeContent: Even those 2 parameters are not mandatory but suggested 1 of it passing as true for more accurate document search.

Date Range Filtering

  • Both start and end dates are required for date range filters
  • Use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ
  • Date filters are inclusive of the specified dates
⚠️ **GitHub.com Fallback** ⚠️