Search

POST /v1/tools/podio/searchPodio

Locator / discovery tool. Finds WHERE apps, items, people, files, tasks, or conversations live across Podio — returns IDs, names, and a snippet of where your keyword matched — using fuzzy full-text search. THIS IS A LOCATOR, NOT A SOURCE OF TRUTH: - Do NOT read field values from these results — rows are match snippets, not records. Fetch the real data with the next-step tools below. - Do NOT count, sum, or total with this tool. "approximate_match_counts" are FUZZY relevance counts (they also match comments and hidden metadata, not just field values) — NEVER report them to the user as an exact total. - Almost every search should be followed by a precise call. NEXT STEP (always follow up): - Read a found item's fields → podio_getItem - Filter/list items by field values (status, date, number, category) → podio_filterItems - Inspect a found app → podio_getApp - Exact counts / sums / totals → podio_aggregateItems WHEN TO USE THIS TOOL: - Finding an app by name (e.g., "Invoices", "Projects", "Leads") → ref_type: 'app' - Finding items/records by keyword (e.g., "Acme Corp", "Invoice #1234") → ref_type: 'item' - Finding a person or contact → ref_type: 'profile' - Finding tasks, files, or conversations by keyword TIPS: - Always set ref_type to filter to a single type — much less noisy. - Start broad (global), then narrow with org_id / space_id / app_id. - Pages are capped at 20 results; use offset to paginate (watch has_more / next_offset).

Parameters

Name	Type	Required	Description
query	string	required	The text to search for
ref_type	string	optional	Filter results to a single type. Recommended — without this you get mixed results. Use 'app' to find apps by name, 'item' to find records, 'profile' to find people. Values: item, task, file, conversation, profile, app
org_id	number	optional	Search within a specific organization only
space_id	number	optional	Search within a specific workspace only
app_id	number	optional	Search within a specific app only
search_fields	array	optional	Limit search to specific fields (e.g., ["title"])
limit	number	optional	Max results per page (1–20, default 20). Podio caps search pages at 20; use offset to paginate.
offset	number	optional	Pagination offset (default: 0)

curl -X POST https://api.syncello.io/v1/tools/podio/searchPodio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
  -d '{
  "query": "example"
}'

{
  "query": "Northwind",
  "scope": {
    "level": "global"
  },
  "returned": 20,
  "has_more": true,
  "next_offset": 20,
  "approximate_match_counts": {
    "item": 42,
    "file": 3,
    "profile": 1,
    "app": 1
  },
  "counts_caveat": "Fuzzy full-text relevance matches (incl. comments & metadata) — NOT an exact total. For exact counts use podio_aggregateItems or podio_filterItems.",
  "next_step": "searchPodio only locates records. Read values → podio_getItem · filter by field values → podio_filterItems · an app → podio_getApp · exact counts/sums → podio_aggregateItems.",
  "results": [
    {
      "type": "item",
      "item_id": 3141592653,
      "app_id": 28471960,
      "app_name": "Deals",
      "title": "Northwind Traders",
      "link": "https://podio.com/acme-corp/deals/items/1"
    },
    {
      "type": "file",
      "file_id": 988776601,
      "title": "northwind-proposal.pdf",
      "link": "https://files.podio.com/988776601",
      "space": {
        "space_id": 7482910,
        "name": "Sales"
      }
    }
  ]
}