Queries

These endpoints use the product and organization attached to your API key. An ID from another product is not a way to change scope. See Authentication for shared authentication and subscription errors.

Examples use Bash and a user-supplied LOUDMINK_API_KEY environment variable. Replace synthetic IDs with IDs returned for your product. Response examples are illustrative, not live data.

GET /api/queries

List tracked searches with pagination. No request body or subscription gate.

Use valid integer pagination values: malformed values are not explicitly rejected with a validation 400 and can cause a server error. Volume sorting puts unknown volumes last in either direction. Visibility sorting uses the stored visibility score; returned engine fields are then plan-masked.

cited and mentioned filters test engines included in the workspace plan. not_visible requires no citation or mention on those engines and excludes pending queries. pendingCount counts all pending queries in the product, independent of the current filters.

curl --get 'https://loudmink.ai/api/queries' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'filter=cited' \
  --data-urlencode 'sort=volume' \
  --data-urlencode 'tags=Priority,Research'

Returns 200 with { queries, total, page, pageSize, totalPages, pendingCount }. Each query includes id, queryText, status, cited, mentioned, lastChecked, createdAt, estimatedMonthlyVolume, volumeStatus, visibilityTrend, tags (objects with id and name), and the five engines' Cited/Mentioned booleans. It does not include response text or citation arrays.

Illustrative empty result:

{
  "queries": [],
  "total": 0,
  "page": 1,
  "pageSize": 20,
  "totalPages": 0,
  "pendingCount": 0
}

Unexpected failures return 500 with { "error": "Failed to fetch queries" }.

GET /api/queries/{id}

Fetch full details for one tracked query. No request body or query parameters.

curl 'https://loudmink.ai/api/queries/query_example' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY"

Returns 200 with { success: true, query }. The query has id, queryText, status, cited, mentioned, createdAt, and available details:

• Aggregate gapAnalysis, citations, and lastChecked.
• For each prefix perplexity, chatgpt, grok, gemini, and claude: Response, Citations, Cited, Mentioned, GapAnalysis, and GapCitations.
• estimatedMonthlyVolume, volumeKeywords, volumeLastCalculated, and volumeStatus.

Stored JSON fields are parsed for this response. Missing optional values are generally omitted, not returned as null. Tags and visibilityTrend are not included here; use the list endpoint for those fields.

For this endpoint, the list endpoint, and history, plan-locked engines have Cited and Mentioned set to false; their response/citation/gap fields are omitted. Aggregate cited/mentioned are recomputed from allowed engines. Non-pending status becomes cited, not_cited (mentioned but not cited), or not_mentioned. Detail citations is assembled from allowed engines and omitted when empty. A locked engine's false flag does not mean a check found no visibility.

Errors: 404 with { success: false, error: "Query not found" }; 500 with { success: false, error: "Failed to fetch query" }.

GET /api/queries/{id}/history

Read stored per-day citation flags in ascending date order. Optional days must contain only digits and represent an integer from 1 through 90. It includes today and the preceding days - 1 UTC calendar days. Omit it to return all stored history. There is no pagination or gap filling.

curl 'https://loudmink.ai/api/queries/query_example/history?days=30' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY"

Returns 200 with { success: true, history }. Entries contain date (YYYY-MM-DD) and the five engines' Cited/Mentioned booleans, with plan masking as above. A query without history returns an empty array.

Errors: 400 with { error: "days must be an integer between 1 and 90" }; 404 with { error: "Query not found" }; 500 with { error: "Failed to fetch citation history" }.

GET /api/queries/{id}/digest

Read the latest stored extraction from AI responses, selected by descending digest date. No request body or query parameters. This reads existing data; it does not generate a digest.

curl 'https://loudmink.ai/api/queries/query_example/digest' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY"

Returns 200 with { query, date, digest }: query is the query text, and digest is the parsed stored JSON. The route does not validate a fixed digest schema or apply the per-engine masking used by query details.

When there is no stored digest, or the stored JSON cannot be parsed, it returns { query, digest: null } without date. Illustrative example:

{ "query": "Example category software", "digest": null }

A missing query returns 404 with { error: "Query not found" }. Unexpected database errors have no route-specific JSON error envelope.

DELETE /api/queries/{id}

Permanently delete one tracked query and write an audit entry. Requires a writable workspace under the subscription gate. No request body. This is not an archive operation: database relations also cascade-delete its citation history, stored citation URLs, digests, and tag links. Tag definitions themselves are not deleted by this operation.

curl -X DELETE 'https://loudmink.ai/api/queries/query_example' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY"

Returns 200 with { "success": true }. Errors: 404 with { success: false, error: "Query not found" }; 500 with { success: false, error: "Failed to delete query" }; subscription failures return 403. A repeat deletion returns 404, not another success.

PUT /api/queries/{id}/tags

Replace all tag links on a query. Requires a writable workspace. Supply JSON with tagIds, an array of existing tag IDs; an empty array removes every tag link. This does not add tags by name or create new tags.

curl -X PUT 'https://loudmink.ai/api/queries/query_example/tags' \
  -H "Authorization: Bearer $LOUDMINK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"tagIds":["tag_example"]}'

The replacement is applied as a single operation. Returns 200 with { "success": true }. Send distinct, valid tag IDs belonging to your organization.

Errors: 400 with { error: "tagIds must be an array" }; 404 with { error: "Query not found" }; 500 with { error: "Failed to set query tags" }, including invalid JSON or database constraint failures; subscription failures return 403.

Actions that an API key cannot perform

The following implemented routes are not callable with a Bearer key alone. A hybrid-auth import does not mean every method supports API keys.

Key-only creation, bulk creation and manual rechecks return 401 with { "error": "Unauthorized" }. Perform these actions inside Loudmink. There is no PATCH /api/queries/{id} handler. API keys can read tags already attached to queries through GET /api/queries and replace a query's tag links through the supported PUT above, but cannot manage the tag definitions themselves.