Signals

GET /v1/signals returns the signals in your workspace, filtered, sorted and paged.

page and limit are clamped, never rejected: limit=500 becomes 100, limit=abc becomes 20, page=0 becomes 1. A value the database does not know is not an error either: status=bogus matches nothing and returns an empty page, and an unrecognised sortBy falls back to priority. Give the flat parameters a comma-separated string, not repeated keys and not status[]=ready; the bracket form arrives as an array and fails the request with a 500.

Three kinds of row are never listed, whatever you ask for: signals folded into a duplicate (mergedIntoId set), signals from a channel whose auto-skip rule silenced them, and deleted signals. Filtering by status=merged therefore returns an empty page. You can still read a merged signal by id.

attachments is always empty on this endpoint, even for a signal that has them. Read the signal by id to see them.

How signal search matches words

The search parameter is word-boundary full-text search, not a substring scan. nima lowercases and tokenises the text and never stems it, so search=fracti does not match fractional, and search=import does not match imports.

With searchMode=prefix, each term matches words that start with it, so fracti finds fractional. Use prefix for as-you-type queries and word (the default) for exact terms. The search text is matched against the preview, extracted intent, content and PM notes, and separately against the stakeholder and product-area lists.

To find a fragment a tokeniser throws away, such as v2. or 500 , use the content field of the filter parameter with the contains operator, which is a plain, case-insensitive substring scan.

The search_signals MCP tool takes a narrower set of inputs and returns a trimmed row; see search_signals tool.

The signal filter parameter

The filter parameter takes one URL-encoded JSON object. It is ANDed with every flat parameter above, so the two compose.

{
  "combinator": "and",
  "conditions": [
    { "field": "classification", "operator": "in", "value": ["bug", "performance"] },
    { "field": "createdAt", "operator": "in_last", "value": { "amount": 14, "unit": "day" } },
    { "field": "inBeacon", "operator": "not_exists" }
  ]
}

A condition is { field, operator, value }. A nested group is { combinator, conditions } and can sit anywhere a condition can. Which operators a field accepts is decided by its type.

The search field and the content field are not the same thing. search runs against a tokenised index and is the fast one. content is a plain, case-insensitive substring scan.

Limits on a filter, all of them a 400 when exceeded: nesting depth 3, 32 conditions, 50 values in one list, 200 characters in one text value, and an in_last amount of 3650.

reactionCount is filterable but is not a field of the signal object. You can filter a list down to signals with many reactions; you cannot sort by it or read the number back.

Signal list paging and the 3000-row cap

The list response carries meta with page, pageSize, totalItems and totalPages. Paging stops hard at 3000 rows: a request whose offset plus page size would pass it is a 400 with details.maxOffset, so at the default limit=20 page 151 fails. Narrow the filter instead of paging deeper.

meta.countMode is usually absent, which means totalItems is an exact count. It appears as "estimated" when the filter uses origin, productArea, stakeholder, inBeacon, hasSpec, or an or group with more than one condition: no index reaches those, so the total is the query planner's guess while the rows themselves are exact. A short final page always reports "exact".

Grouped signal lists

Setting groupBy replaces the paginated shape with { "groups": [{ "key", "label", "count", "data" }], "meta": { "totalItems" } }. Grouping happens over the rows of the current page only, so count is how many of that group landed on this page, not how many exist. Signals with no value for the grouped field land under unknown.

Errors from list signals

GET /v1/signals/facets returns how many signals each value of a field would leave, under the same scope the list is using. It is a second call rather than a field on the list because it runs under its own budget and its own cache. It has no MCP tool.

status, classification, source, impact, search, grouped and inSpec are taken here too: the same flat parameters the list takes, with the same meaning. searchMode is not taken here, so search always matches whole words.

Counts drill sideways: for the field being counted, that field's own top-level conditions are dropped from filter and everything else is kept, so ticking a second value of the same facet widens the list instead of emptying it. The flat parameters are not dropped, so status=ready&fields=status reports 0 for every status but ready.

Every value the schema declares is present, zero-filled. unset counts rows whose value is null, which is a bucket of its own and never one of the values. An array facet returns at most 50 values, highest count first. arrays is null unless you asked for an array field by name.

Errors from signal facet counts

GET /v1/signals/{id} returns one signal by id. Unlike the list, it returns merged and auto-skipped signals, and it fills attachments. It does not fill linkedEntities, which is always [] here and populated on the list: the two endpoints are complementary, not interchangeable.

The body is a single signal object, the same shape as one element of the list's data. Its sourceDocument.available field says whether a fuller original exists and can be fetched with the source endpoint.

proxyUrl is honest about where the file is, but the route behind it needs a signed-in session: a key gets a 403 there.

Errors from get a signal

GET /v1/signals/{id}/source fetches the original document behind a signal. nima stores the excerpt that produced a signal, never the original. This route fetches the original live, with your workspace's own credential for that integration: the whole Slack thread, the full GitHub issue or pull request discussion, the HubSpot record, the Granola note, the PostHog or Sentry issue, the Linear issue with its comments, the ClickUp task with its thread. Nothing is cached and nothing is written.

A page is at most 40,000 bytes. When nextCursor is not null, pass it back as cursor for the next page, unchanged, with the same part. A cursor belongs to one signal, one source and one part; reusing it anywhere else is a 400, and so is continuing to page a document that changed underneath you.

changedSinceIngest compares a hash of the unit that produced the signal against the same unit today. It is null when nima stored no hash or the source has no stable unit, which is not the same as false.

duplicates lists the signals folded into this one, at most 50. Each has its own original: fetch them by their own id.

Source document availability values

The per-workspace fetch budget, per minute, per source: Slack 20; HubSpot, Granola and ClickUp 30; GitHub, PostHog, Sentry and Linear 60. Past it you get rate_limited rather than a 429.

Errors from get the original document behind a signal

POST /v1/signals files one piece of feedback into the workspace by hand. It is the right endpoint for something a person or an agent observed. For a system posting on a schedule, use an inbound webhook instead: the webhook endpoint de-duplicates and this one does not.

Unknown fields are stripped silently rather than rejected.

What nima does after a signal is created

The signal is written with source: "manual", status: "pending", confidence: 1, a generated sourceId, and preview set to the first 280 characters of content. Then extraction is queued and the response is sent: 201, with the created signal.

Manual signals are never de-duplicated. There is no idempotency key on this route, so a retried POST creates a second signal, and nothing folds the two together at write time or later: nima does not merge signals automatically. Only a person merges duplicates, with a signed-in session.

Errors from create a signal