Skip to content
Optiwork API Docs

Semantic search

POST
/semantic/search
curl --request POST \
  --url https://flow.work.optidata.cloud/api/semantic/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "question": "How do I enable two-factor authentication?", "top_k": 2 }'

Answers a natural-language question with the passages of published pages whose meaning is closest to it — not just the ones sharing its words. Each result is one passage (chunk) of a page’s current published version, with the page, its category and a similarity between 0 and 1.

Only pages the caller can see are searched: those in categories visible to them, plus pages made public. Passages below a minimum similarity are left out, so a search can legitimately return no results. Newly published text becomes searchable shortly after publication.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
question
required

The question or phrase to search for.

string
>= 3 characters <= 2000 characters
category_id

Only search pages of this category.

integer | null
top_k

Maximum number of passages to return.

integer | null
default: 5 >= 1 <= 20
Examples
Examplequestion
{
  "question": "How do I enable two-factor authentication?",
  "top_k": 2
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The best-matching passages, most similar first.

Media typeapplication/json
object
data
required
object
question
required

The question, echoed.

string
results
required
Array<object>
object
chunk
required

The passage within the page’s published version.

object
id
integer
index

Position of the passage in the page, from 0.

integer
page
required
object
id
integer
identifier
string
title
string
page_content_id

The published version the passage comes from.

integer
category
required
object
id
integer
identifier
string | null
name
string
content
required

The passage’s text.

string
similarity
required

How close the passage is to the question; higher is closer.

number
<= 1
meta
required
object
total_results
required

Number of passages returned.

integer
top_k
required

The maximum that was in effect.

integer
Examples
{
  "data": {
    "question": "How do I enable two-factor authentication?",
    "results": [
      {
        "chunk": {
          "id": 439,
          "index": 0
        },
        "page": {
          "id": 2927,
          "identifier": "dDbBQQtcKr",
          "title": "Onboarding checklist",
          "page_content_id": 4508
        },
        "category": {
          "id": 993,
          "identifier": "jYpV3A",
          "name": "Onboarding"
        },
        "content": "Request a laptop and set up your Optiwork account on day one. Read the security handbook and enable two-factor authentication.",
        "similarity": 0.6173
      }
    ],
    "meta": {
      "total_results": 1,
      "top_k": 2
    }
  }
}

401

Section titled “401”

No authentication key was sent.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

419

Section titled “419”

The authentication key is expired or not recognised. Get a fresh one and retry.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Exampleexpired
{
  "error": "JWT passport expired: Passport expired"
}

422

Section titled “422”

The body failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
{
  "message": "The question must be at least 3 characters.",
  "errors": {
    "question": [
      "The question must be at least 3 characters."
    ]
  }
}