Knowledge

Download schema

Retrieve knowledge nodes by ID.

POST

https://api.stackinternal.com

/v1/knowledge/nodes

Retrieve persisted knowledge nodes by their unique node IDs. Missing IDs are omitted from the response.

Retrieve knowledge nodes by ID. › Request Body

The request for retrieving persisted nodes by node ID.

GetNodesByIdsRequest

nodeIds

string[] · minItems: 1 · maxItems: 100 · required

Node IDs to retrieve. Duplicates are ignored.

Example: ["9588aca8-8995-4c14-a11f-fb442f2bc67c","bd1d2fa1-5169-42c3-bb42-3c020b56417f"]

Retrieve knowledge nodes by ID. › Responses

Success.

The response containing matching persisted nodes.

GetNodesByIdsResponse

object · required

The matching nodes keyed by node ID. Missing requested IDs are omitted.

POST/v1/knowledge/nodes

curl https://api.stackinternal.com/v1/knowledge/nodes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "nodeIds": [
    "9588aca8-8995-4c14-a11f-fb442f2bc67c",
    "bd1d2fa1-5169-42c3-bb42-3c020b56417f"
  ]
}'

Example Request Body

{
  "nodeIds": [
    "9588aca8-8995-4c14-a11f-fb442f2bc67c",
    "bd1d2fa1-5169-42c3-bb42-3c020b56417f"
  ]
}

json

application/json

Example Responses

{
  "nodes": {
    "key": {
      "nodeId": "00000000-0000-0000-0000-000000000000",
      "text": "text",
      "externalSourceUrl": "https://www.example.com/path/to/resource",
      "classificationSignals": [
        "string"
      ],
      "creationMetadata": {
        "author": {
          "userId": "userId",
          "internalUserId": "internalUserId"
        },
        "createdAt": "2024-08-25T15:00:00Z",
        "editedAt": "2024-08-25T15:00:00Z"
      },
      "ingestionMetadata": {
        "source": "source",
        "sourceId": "sourceId",
        "archetypeType": "archetypeType",
        "archetypeVersion": "archetypeVersion",
        "sourceContext": {
          "id": "id",
          "name": "name"
        },
        "ingestedAt": "2024-08-25T15:00:00Z",
        "ingestedBy": "ingestedBy"
      },
      "documentDimension": {
        "title": "title"
      },
      "trustDimension": {
        "score": 0,
        "evaluatorVersion": "evaluatorVersion",
        "assignedAt": "2024-08-25T15:00:00Z"
      },
      "explicitUserEngagementDimension": {
        "score": 0,
        "views": 0
      },
      "relations": [
        {
          "type": "QuestionTo",
          "sourceNodeId": "00000000-0000-0000-0000-000000000000",
          "targetNodeId": "00000000-0000-0000-0000-000000000000",
          "isAccepted": true
        }
      ],
      "deleted": false,
      "tenantId": "00000000-0000-0000-0000-000000000000",
      "contentId": "contentId"
    }
  }
}

json

application/json

Retrieve a knowledge node by ID.

GET

https://api.stackinternal.com

/v1/knowledge/nodes/{nodeId}

Retrieve a persisted knowledge node by its unique node ID.

Retrieve a knowledge node by ID. › path Parameters

nodeId

string · uuid · required

The node ID of the node to retrieve

Retrieve a knowledge node by ID. › Responses

Success.

A persisted node.

Node

nodeId

string · uuid · required

Node ID.

text

string · required

The node text.

classificationSignals

string[] · minItems: 0 · required

Signals used to classify the node.

CreationMetadata · required

Creation metadata for the node.

IngestionMetadata · required

Ingestion metadata for the node.

TrustDimension · required

Trust evaluation data.

NodeRelation[] · minItems: 0 · required

Relations with other nodes.

deleted

boolean · required

Whether the node is deleted.

Example: false

tenantId

string · uuid · required

Tenant ID

contentId

string · required

Content ID.

externalSourceUrl

string | null · uri

Human-resolvable URL of this node at its external source system. Distinct from ingestionMetadata.source (the system name, e.g. "stackinternalcommunity") and ingestionMetadata.sourceId (the source's internal identifier, e.g. "5") — this is the link a human would follow to read the original content. Null when the source does not expose a stable URL.

object

Document-specific metadata.

object

Explicit user engagement data from the source system.

GET/v1/knowledge/nodes/{nodeId}

curl https://api.stackinternal.com/v1/knowledge/nodes/:nodeId \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "nodeId": "00000000-0000-0000-0000-000000000000",
  "text": "text",
  "externalSourceUrl": "https://www.example.com/path/to/resource",
  "classificationSignals": [
    "string"
  ],
  "creationMetadata": {
    "author": {
      "userId": "userId",
      "internalUserId": "internalUserId"
    },
    "createdAt": "2024-08-25T15:00:00Z",
    "editedAt": "2024-08-25T15:00:00Z"
  },
  "ingestionMetadata": {
    "source": "source",
    "sourceId": "sourceId",
    "archetypeType": "archetypeType",
    "archetypeVersion": "archetypeVersion",
    "sourceContext": {
      "id": "id",
      "name": "name"
    },
    "ingestedAt": "2024-08-25T15:00:00Z",
    "ingestedBy": "ingestedBy"
  },
  "documentDimension": {
    "title": "title"
  },
  "trustDimension": {
    "score": 0,
    "evaluatorVersion": "evaluatorVersion",
    "assignedAt": "2024-08-25T15:00:00Z"
  },
  "explicitUserEngagementDimension": {
    "score": 0,
    "views": 0
  },
  "relations": [
    {
      "type": "QuestionTo",
      "sourceNodeId": "00000000-0000-0000-0000-000000000000",
      "targetNodeId": "00000000-0000-0000-0000-000000000000",
      "isAccepted": true
    }
  ],
  "deleted": false,
  "tenantId": "00000000-0000-0000-0000-000000000000",
  "contentId": "contentId"
}

json

application/json

Search indexed knowledge nodes.

POST

https://api.stackinternal.com

/v1/knowledge/search

Search persisted knowledge nodes with the selected algorithm. Results are ordered by descending trust score and exclude deleted nodes. Each result's score remains the algorithm's relevance score.

Search indexed knowledge nodes. › Request Body

The request for searching indexed nodes.

SearchRequest

query

string · minLength: 1 · maxLength: 5000 · required

The search query, which must contain at least one non-whitespace character.

Example: SSO troubleshooting

limit

integer · int32 · min: 1 · max: 100 · required

The number of results to return.

Default: 10

algorithm

string | null · enum

The search algorithm to use.

Enum values:

lexical_v1

semantic_v1

hybrid_v1

Default: hybrid_v1

scopeIds

array | null

The scope IDs to filter search results by.

Search indexed knowledge nodes. › Responses

Success.

The response containing search results.

SearchResponse

hasIndexedNodes

boolean · required

Indicates whether the tenant search index is available for node search. This is false only when the tenant index does not exist. When this is true and results is empty, the index exists but either contains no indexed nodes or no nodes matched the query.

SearchResult[] · minItems: 0 · required

The search results.

total

integer · int32 · min: 0 · required

Total number of matching nodes.

userAclGrants

string[] · required

The ACL grant tags resolved for the requesting user. Each string is a JSON array containing the subject provider, kind, and external ID.

POST/v1/knowledge/search

curl https://api.stackinternal.com/v1/knowledge/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "query": "SSO troubleshooting",
  "algorithm": "hybrid_v1",
  "limit": 10,
  "scopeIds": [
    "4d8f3d4b-4e9f-48bc-89a0-cfbcf8a60df3"
  ]
}'

Example Request Body

{
  "query": "SSO troubleshooting",
  "algorithm": "hybrid_v1",
  "limit": 10,
  "scopeIds": [
    "4d8f3d4b-4e9f-48bc-89a0-cfbcf8a60df3"
  ]
}

json

application/json

Example Responses

{
  "hasIndexedNodes": true,
  "results": [
    {
      "node": {
        "nodeId": "00000000-0000-0000-0000-000000000000",
        "text": "text",
        "externalSourceUrl": "https://www.example.com/path/to/resource",
        "classificationSignals": [
          "string"
        ],
        "creationMetadata": {
          "author": {
            "userId": "userId",
            "internalUserId": "internalUserId"
          },
          "createdAt": "2024-08-25T15:00:00Z",
          "editedAt": "2024-08-25T15:00:00Z"
        },
        "ingestionMetadata": {
          "source": "source",
          "sourceId": "sourceId",
          "archetypeType": "archetypeType",
          "archetypeVersion": "archetypeVersion",
          "sourceContext": {
            "id": "id",
            "name": "name"
          },
          "ingestedAt": "2024-08-25T15:00:00Z",
          "ingestedBy": "ingestedBy"
        },
        "documentDimension": {
          "title": "title"
        },
        "trustDimension": {
          "score": 0,
          "evaluatorVersion": "evaluatorVersion",
          "assignedAt": "2024-08-25T15:00:00Z"
        },
        "explicitUserEngagementDimension": {
          "score": 0,
          "views": 0
        },
        "relations": [
          {
            "type": "QuestionTo",
            "sourceNodeId": "00000000-0000-0000-0000-000000000000",
            "targetNodeId": "00000000-0000-0000-0000-000000000000",
            "isAccepted": true
          }
        ],
        "deleted": false,
        "tenantId": "00000000-0000-0000-0000-000000000000",
        "contentId": "contentId"
      },
      "score": 0
    }
  ],
  "total": 0,
  "userAclGrants": [
    "string"
  ]
}

json

application/json

Content OAuth Applications