`POST /api/query`.

POST

/api/query

The door onto the composition contract: a caller sends a plan, the server answers it or refuses
it. Everything before this route built a door that nothing could knock on.

The pipeline is not assembled here. [query_read::prepare] owns the order — shape-gate,
then embed, then validate — and is the only constructor of a ValidatedComposition, so this
handler cannot run an unvalidated plan even by mistake. Spelling the order out here would make
this the second place that knows it, and the day the MCP tool and the CLI arrive, the third and
fourth.

The refusal branch is the only thing that differs from [super::search::search], whose
shape this otherwise copies: search_select takes params and answers, while prepare may
refuse first.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

One entry in returned per outcome.returns — no more, no fewer — keyed by stage name rather than merged into one ordered list, so combining two acts' rows takes a deliberate act by the caller. trace covers EVERY stage, including those whose rows were not returned, because the pipe carries ids rather than rows and an untraced composition is a black box with an answer at the end.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/query' \
--header 'X-Temper-Surface;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "outcome": {
        "returns": [
            {
                "stage": "string",
                "with": [
                    "body"
                ]
            }
        ]
    },
    "stages": [
        {
            "act": "find-exact",
            "edge_filter": null,
            "inputs": [
                {
                    "as": "bound",
                    "from": "caller",
                    "ids": {
                        "ids": [
                            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
                        ],
                        "kind": "resource",
                        "provenance": null
                    }
                }
            ],
            "intention": null,
            "name": "string",
            "properties": [
                {
                    "key": "string",
                    "op": {
                        "op": "has_key"
                    }
                }
            ],
            "resource_filter": null,
            "terms": {
                "property1": 0,
                "property2": 0
            }
        }
    ]
}'

Response Example

200 - Example 1

{
    "returned": {
        "property1": {
            "act": "find-exact",
            "disposition": "answered",
            "extent": {
                "extent": "complete"
            },
            "input_ids": 0,
            "input_unusable": 0,
            "narrowed_by": [
                {
                    "admitted": 0,
                    "excluded": 0,
                    "key": "string",
                    "value": "string"
                }
            ],
            "orders_by": null,
            "produced": {
                "hits": [
                    {
                        "located_at": null,
                        "resource": {
                            "body_hash": "string",
                            "body_storage": null,
                            "cogmap_id": "b2008c45-9f31-4aae-8f49-0cadcb6ad25e",
                            "cogmap_name": "string",
                            "content": "string",
                            "context_name": "string",
                            "context_owner_ref": "string",
                            "context_ref": "string",
                            "context_slug": "string",
                            "created": "2019-08-24T14:15:22.123Z",
                            "doc_type_name": "string",
                            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                            "ingest_state": null,
                            "is_active": true,
                            "kb_context_id": null,
                            "managed_meta": {
                                "temper-branch": "string",
                                "temper-effort": "string",
                                "temper-llm-model": "string",
                                "temper-llm-run": "string",
                                "temper-mode": "string",
                                "temper-pr": "string",
                                "temper-provenance": "string",
                                "temper-seq": 0,
                                "temper-stage": "string",
                                "temper-status": "string"
                            },
                            "open_meta": null,
                            "origin_uri": "string",
                            "originator_profile_id": "20c67e1c-fb7d-4020-a7af-db154cdd188d",
                            "owner_handle": "string",
                            "owner_profile_id": "21e0f360-ea66-4de2-b817-b59c51592556",
                            "ref": "string",
                            "title": "string",
                            "updated": "2019-08-24T14:15:22.123Z"
                        },
                        "scoring": {
                            "score": 0,
                            "score_kind": "fts_norm"
                        },
                        "via": [
                            {
                                "edge_kind": "express",
                                "label": "string",
                                "polarity": "forward",
                                "seed_id": "28b1c536-e0f9-4dd7-9906-e2ce7cf3a870",
                                "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
                                "target_id": "d3bcdc92-4191-401b-ad0c-42056c6efab9"
                            }
                        ]
                    }
                ],
                "produced": "resources"
            },
            "refusal": null,
            "terms_applied": {
                "property1": 0,
                "property2": 0
            },
            "total": 0
        },
        "property2": {
            "act": "find-exact",
            "disposition": "answered",
            "extent": {
                "extent": "complete"
            },
            "input_ids": 0,
            "input_unusable": 0,
            "narrowed_by": [
                {
                    "admitted": 0,
                    "excluded": 0,
                    "key": "string",
                    "value": "string"
                }
            ],
            "orders_by": null,
            "produced": {
                "hits": [
                    {
                        "located_at": null,
                        "resource": {
                            "body_hash": "string",
                            "body_storage": null,
                            "cogmap_id": "b2008c45-9f31-4aae-8f49-0cadcb6ad25e",
                            "cogmap_name": "string",
                            "content": "string",
                            "context_name": "string",
                            "context_owner_ref": "string",
                            "context_ref": "string",
                            "context_slug": "string",
                            "created": "2019-08-24T14:15:22.123Z",
                            "doc_type_name": "string",
                            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                            "ingest_state": null,
                            "is_active": true,
                            "kb_context_id": null,
                            "managed_meta": {
                                "temper-branch": "string",
                                "temper-effort": "string",
                                "temper-llm-model": "string",
                                "temper-llm-run": "string",
                                "temper-mode": "string",
                                "temper-pr": "string",
                                "temper-provenance": "string",
                                "temper-seq": 0,
                                "temper-stage": "string",
                                "temper-status": "string"
                            },
                            "open_meta": null,
                            "origin_uri": "string",
                            "originator_profile_id": "20c67e1c-fb7d-4020-a7af-db154cdd188d",
                            "owner_handle": "string",
                            "owner_profile_id": "21e0f360-ea66-4de2-b817-b59c51592556",
                            "ref": "string",
                            "title": "string",
                            "updated": "2019-08-24T14:15:22.123Z"
                        },
                        "scoring": {
                            "score": 0,
                            "score_kind": "fts_norm"
                        },
                        "via": [
                            {
                                "edge_kind": "express",
                                "label": "string",
                                "polarity": "forward",
                                "seed_id": "28b1c536-e0f9-4dd7-9906-e2ce7cf3a870",
                                "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
                                "target_id": "d3bcdc92-4191-401b-ad0c-42056c6efab9"
                            }
                        ]
                    }
                ],
                "produced": "resources"
            },
            "refusal": null,
            "terms_applied": {
                "property1": 0,
                "property2": 0
            },
            "total": 0
        }
    },
    "trace": {
        "stages": [
            {
                "act": "find-exact",
                "disposition": "answered",
                "extent": {
                    "extent": "complete"
                },
                "input_ids": 0,
                "input_unusable": 0,
                "inputs": [
                    {
                        "ids": 0,
                        "relation": "bound",
                        "source": {
                            "source": "upstream",
                            "stage": "string"
                        }
                    }
                ],
                "narrowed_by": [
                    {
                        "admitted": 0,
                        "excluded": 0,
                        "key": "string",
                        "value": "string"
                    }
                ],
                "produced_ids": 0,
                "refusal": null,
                "stage": "string",
                "terms_applied": {
                    "property1": 0,
                    "property2": 0
                }
            }
        ]
    }
}

Modified at 2026-08-19 12:26:18

list_auth_links

assert