--- title: "POST /api/v1/answers" method: POST path: "/api/v1/answers" --- # POST /api/v1/answers `POST /api/v1/answers` ## Request - Base URL: `https://falconer.com` (the document declares no server; this is the origin it was published from) - URL: `https://falconer.com/api/v1/answers` - Auth: none declared ## Headers - `x-organization-id` string: Required when using OAuth bearer tokens. ## Request body - AskRequest - `question` string, required: Natural-language question for the Falconer agent to answer over this workspace. - `conversationId` string: Continue a previous ask conversation by passing the conversationId it returned. - `allowQuestions` boolean: Let the agent stop and ask the user structured questions (returned in pendingQuestions) instead of guessing. Set only when a person sees the questions and can answer them. ## Response `200` Synthesized agent answer with citations - AskResponse - `answer` string, required: Answer markdown; inline citations are numbered [N]. - `citations` object[], required - `index` number, required: Matches the inline [N] marker (0-based). - `id` string, required: Source document id. - `title` string, required - `url` string, required - `conversationId` string, required - `pendingQuestions` AskQuestions: Questions the agent needs answered before it can continue, to show one at a time in order. single_choice takes exactly one option, multiple_choice any number, and text a free-text answer. When allowOther is true the user may answer in their own words instead of picking an option; optional questions may be skipped. - `title` string, required: One line saying what the answers are for, such as "A few details before I draft the guide". Used where the questions are announced, such as notifications, not shown above them. - `questions` union[], required: The user sees one question at a time, in this order. Ask only what you cannot decide yourself. - union - object - `type` 'single_choice', required: Radio buttons: exactly one of a few options. - `question` string, required: The question, ending with a question mark. - `options` object[], required: 2 to 8 distinct options. Never add an "Other" option yourself. - `label` string, required: The choice in a few words. Put your recommended option first. - `description` string: One short line on what picking this means, when not obvious. - `preview` string: Markdown shown beside the options while this one is highlighted: an outline, a draft paragraph, a code snippet. Use it when seeing the result helps the user choose between options. - `allowOther` boolean: Adds an "Other" choice with a text field. Leave on unless the options are truly exhaustive (yes/no, a fixed list). - `optional` boolean: Let the user skip this question. - object - `type` 'multiple_choice', required: Checkboxes: any number of a few options. - `question` string, required: The question, ending with a question mark. - `options` object[], required: 2 to 8 distinct options. Never add an "Other" option yourself. - `label` string, required: The choice in a few words. Put your recommended option first. - `description` string: One short line on what picking this means, when not obvious. - `preview` string: Markdown shown beside the options while this one is highlighted: an outline, a draft paragraph, a code snippet. Use it when seeing the result helps the user choose between options. - `allowOther` boolean: Adds an "Other" choice with a text field. Leave on unless the options are truly exhaustive (yes/no, a fixed list). - `optional` boolean: Let the user skip this question. - object - `type` 'select', required: A dropdown with search, for a long list of options (more than 8), such as teams, projects, or regions. - `question` string, required: The question, ending with a question mark. - `options` object[], required: 2 to 50 distinct options. Never add an "Other" option yourself. - `label` string, required: The choice in a few words. Put your recommended option first. - `description` string: One short line on what picking this means, when not obvious. - `multiple` boolean: Let the user pick several. - `allowOther` boolean: Adds an "Other" choice with a text field. Leave on unless the options are truly exhaustive (yes/no, a fixed list). - `optional` boolean: Let the user skip this question. - object - `type` 'text', required: A free-text field, for answers you cannot list as options. - `question` string, required: The question, ending with a question mark. - `placeholder` string: Example answer shown in the empty field. - `optional` boolean: Let the user skip this question. - object - `type` 'date', required: A date picker, for a deadline, a meeting day, or a range start. - `question` string, required: The question, ending with a question mark. - `includeTime` boolean: Ask for a time of day as well as the date. - `optional` boolean: Let the user skip this question. - object - `type` 'entity', required: A search picker over this workspace: Falconer documents or people in the organization. Use it instead of asking the user to type a name. - `question` string, required: The question, ending with a question mark. - `entity` 'document' | 'person', required - `multiple` boolean: Let the user pick several. - `optional` boolean: Let the user skip this question. - object - `type` 'confirm', required: A yes or no confirmation before something costly or hard to undo. - `question` string, required: The question, ending with a question mark. - `details` string, required: Exactly what will happen if they confirm, including what cannot be undone. - `confirmLabel` string: The confirm choice, naming the action, such as "Delete 12 docs". - `declineLabel` string - `optional` boolean: Let the user skip this question. - object - `type` 'schedule', required: A recurring cadence picker (every N minutes or hours, daily, weekly, monthly, at a time of day), for how often something should run. - `question` string, required: The question, ending with a question mark. - `suggestedCron` string: Five-field cron expression to preselect, such as "0 9 * * 1-5" for weekdays at 9am. - `optional` boolean: Let the user skip this question. ## Other responses - `400`: Bad request - `402`: Organization credit balance is negative or member monthly credit limit has been reached - `404`: Conversation not found --- [API](https://skmtc.dev/falconer/apis/falconer-public-api.md) · [All operations](https://skmtc.dev/falconer/apis/falconer-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/falconer/apis/falconer-public-api/revisions/7b303b7ddf6a?raw)