Generate knowledge

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate knowledge

> Queue one knowledge-generation job from candidate text, with optional source or inbox linkage.

Use this route when you already have the candidate content you want to turn into knowledge and need Fini to process it as a single background job.

<Info>
  This route always requires `candidateKnowledge`. If you want Fini to generate directly from stored source content, use [Bulk generate knowledge](/en/api-reference/bulk-generate-knowledge) instead. `isDraft` defaults to `true`.
</Info>

## Origins

| Origin | Use it for | Extra required field |
| - | - | - |
| `MAGIC_ARTICLE` | Raw candidate text that is not tied to another Fini record | None |
| `SOURCE_IMPORT` | Candidate text you want to associate with one ingested source record | `documentId` |
| `INBOX_SUGGESTION` | Candidate text you want to associate with one inbox event | `hcEventId` |

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `write` scope.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Body parameters

<ParamField body="candidateKnowledge" type="string" required>
  Candidate content to turn into knowledge.
</ParamField>

<ParamField body="origin" type="string" required>
  Origin for the content. Allowed values are `MAGIC_ARTICLE`, `SOURCE_IMPORT`, and `INBOX_SUGGESTION`.
</ParamField>

<ParamField body="documentId" type="string">
  Required when `origin` is `SOURCE_IMPORT`. This is the ingested source ID you want to link the generated result to.
</ParamField>

<ParamField body="hcEventId" type="string">
  Required when `origin` is `INBOX_SUGGESTION`. This is the inbox event ID you want to link the generated result to.
</ParamField>

<ParamField body="restrictedOps" type="array">
  Optional operation restrictions passed through to the generation pipeline. Use this to limit what Fini is allowed to do when it decides how to apply the generated knowledge.
</ParamField>

<ParamField body="instructions" type="string">
  Additional generation instructions.
</ParamField>

<ParamField body="botId" type="string">
  Optional agent ID to scope the generated content to.
</ParamField>

<ParamField body="isDraft" type="boolean" default={true}>
  Whether the generated result should remain a draft.
</ParamField>

## `restrictedOps` values

Use `restrictedOps` to limit the operation choices available to the knowledge-generation pipeline for that request.

| Value | Meaning |
| - | - |
| `ADD_ARTICLE_TO_FOLDER` | Allow Fini to create a new article in an existing folder. |
| `UPDATE_ARTICLE` | Allow Fini to update an existing article that the pipeline selects as the best match. |
| `DO_NOTHING` | Allow Fini to decide that no knowledge change should be applied. When `isDraft` is `true`, this still creates a reviewable draft/no-op record. |

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request POST \
    --url 'https://api-prod.usefini.com/v2/knowledge/public' \
    --header 'Authorization: Bearer fini_your_api_key' \
    --header 'Content-Type: application/json' \
    --data '{
      "candidateKnowledge": "Customers on annual plans can cancel at the end of the current billing term.",
      "origin": "MAGIC_ARTICLE",
      "botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
      "isDraft": true
    }'
  ~~~

  ~~~python Python theme={null}
  import requests

  response = requests.post(
      "https://api-prod.usefini.com/v2/knowledge/public",
      headers={
          "Authorization": "Bearer fini_your_api_key",
          "Content-Type": "application/json",
      },
      json={
          "candidateKnowledge": "Customers on annual plans can cancel at the end of the current billing term.",
          "origin": "MAGIC_ARTICLE",
          "botId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
          "isDraft": True,
      },
  )
  job = response.json()
  ~~~

  ~~~javascript Node.js theme={null}
  const response = await fetch("https://api-prod.usefini.com/v2/knowledge/public", {
    method: "POST",
    headers: {
      Authorization: "Bearer fini_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      candidateKnowledge:
        "Customers on annual plans can cancel at the end of the current billing term.",
      origin: "MAGIC_ARTICLE",
      botId: "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
      isDraft: true,
    }),
  });
  const job = await response.json();
  ~~~
</RequestExample>

## Response

<ResponseField name="backgroundJobId" type="string">
  Background job ID for the queued generation request.
</ResponseField>

<ResponseExample>
  ~~~json 200 OK theme={null}
  {
    "backgroundJobId": "4cfcf2cc-7a06-4de2-b460-5b991fe6236a"
  }
  ~~~
</ResponseExample>

## Next step

Poll the queued job with [Check knowledge jobs](/en/api-reference/check-knowledge-jobs). If you left `isDraft` at its default `true`, review or publish the resulting draft before expecting live agent answers to change.

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    The request body is malformed, `candidateKnowledge` is missing, `origin` is invalid, or the origin-specific required field is missing.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The API key does not include the `write` scope.
  </Accordion>

  <Accordion title="Generation completed but nothing changed live" icon="circle-question">
    Expected when `isDraft` was left at its default `true`. Poll the job status, then review or publish the resulting draft through the article workflow.
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Fini failed while queueing or processing the generation job. Retry once, then inspect the job with [Check knowledge jobs](/en/api-reference/check-knowledge-jobs).
  </Accordion>
</AccordionGroup>


## Related topics

- [Bulk generate knowledge](/en/api-reference/bulk-generate-knowledge.md)
- [Check knowledge jobs](/en/api-reference/check-knowledge-jobs.md)
- [Overview](/en/api-reference/knowledge.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.