Queries API

The Queries API powers the Tune page, providing operations over the query curation lifecycle and access to reuse statistics.

Endpoints

Method	Endpoint	Description
GET	/api/v1/aim/queries/stats	Query count breakdown by status
GET	/api/v1/aim/queries/pending	List pending approval queries
GET	/api/v1/aim/queries/approved	List approved templates
GET	/api/v1/aim/queries/declined	List AIM-declined queries
GET	/api/v1/aim/queries/rejected	List admin-rejected queries
POST	/api/v1/aim/queries/test-cypher	Execute read-only query for testing
POST	/api/v1/aim/queries/{id}/approve	Approve a pending query
POST	/api/v1/aim/queries/{id}/reject	Reject a pending query
POST	/api/v1/aim/queries/{id}/amend	Amend and approve a query
DELETE	/api/v1/aim/queries/{id}	Delete a query

---

Examples

Query Stats

curl https://yourorg.squadai.uk/api/v1/aim/queries/stats \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "pending_approval": 7,
  "approved": 42,
  "rejected": 3,
  "declined": 1,
  "total": 53
}

List Pending Queries

Returns queries awaiting admin approval, with similarity context and Cypher attempts.

curl "https://yourorg.squadai.uk/api/v1/aim/queries/pending?skip=0&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "queries": [
    {
      "id": "q-a1b2c3",
      "text": "What are the active fault schedules for reactor unit 3?",
      "status": "pending",
      "risk_level": "low",
      "timestamp": "2026-03-17T10:30:00Z",
      "similarity_matched": false,
      "user_id": "user-001",
      "actor": "aim",
      "attempts": [
        {
          "id": "ca-001",
          "cypher_text": "MATCH (fs:FaultSchedule)-[:APPLIES_TO]->(u:Unit {id: 3}) WHERE fs.status = 'active' RETURN fs",
          "attempt_number": 1,
          "success": true,
          "error_message": null,
          "result_count": 3,
          "timestamp": "2026-03-17T10:30:02Z"
        }
      ],
      "request_count": 2
    }
  ],
  "total": 7,
  "skip": 0,
  "limit": 20
}

List Approved Queries

Approved templates include the final Cypher and reuse statistics.

curl "https://yourorg.squadai.uk/api/v1/aim/queries/approved?skip=0&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "queries": [
    {
      "id": "q-d4e5f6",
      "text": "Show all documents linked to workflow W-101",
      "status": "approved",
      "risk_level": "low",
      "timestamp": "2026-03-15T08:00:00Z",
      "cypher_id": "ca-010",
      "cypher_text": "MATCH (w:Workflow {id: 'W-101'})-[:USES]->(d:Document) RETURN d",
      "result_count": 5,
      "reuse_count": 12
    }
  ],
  "total": 42,
  "skip": 0,
  "limit": 20
}

Approve a Query

Optionally specify a cypher_id to promote a specific Cypher attempt.

curl -X POST https://yourorg.squadai.uk/api/v1/aim/queries/q-a1b2c3/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher_id": "ca-001"}'

Response 200

{
  "id": "q-a1b2c3",
  "status": "approved",
  "cypher_id": "ca-001"
}

Reject a Query

curl -X POST https://yourorg.squadai.uk/api/v1/aim/queries/q-a1b2c3/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Query returns overly broad results — needs a date filter"}'

Response 200

{
  "id": "q-a1b2c3",
  "status": "rejected"
}

Amend and Approve

Modify the natural-language text, the Cypher, or both before approving. At least one of text or cypher_text is required.

curl -X POST https://yourorg.squadai.uk/api/v1/aim/queries/q-a1b2c3/amend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What are the active fault schedules for reactor unit 3 in 2026?",
    "cypher_text": "MATCH (fs:FaultSchedule)-[:APPLIES_TO]->(u:Unit {id: 3}) WHERE fs.status = '\''active'\'' AND fs.year = 2026 RETURN fs"
  }'

Response 200

{
  "id": "q-a1b2c3",
  "status": "approved",
  "cypher_id": "ca-002"
}

Test Cypher

Run a read-only Cypher query against the knowledge graph before committing it.

curl -X POST https://yourorg.squadai.uk/api/v1/aim/queries/test-cypher \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (fs:FaultSchedule) WHERE fs.status = '\''active'\'' RETURN fs.name, fs.status LIMIT 5"}'

Response 200

{
  "success": true,
  "data": [
    {"fs.name": "FS-2026-001", "fs.status": "active"},
    {"fs.name": "FS-2026-003", "fs.status": "active"}
  ],
  "error": null,
  "record_count": 2
}

Delete a Query

curl -X DELETE https://yourorg.squadai.uk/api/v1/aim/queries/q-a1b2c3 \
  -H "Authorization: Bearer $TOKEN"

Response 200

{
  "id": "q-a1b2c3",
  "status": "deleted"
}