API docs by Redocly

Octopia Knowledge Graph API (1.1.0)

Download OpenAPI specification:

API Support: support@sinoia.fr

API du Knowledge Graph Octopia.

Deux surfaces :

  • Ingestion connecteurs (POST /octopia/api/ingest) : les connecteurs externes poussent leurs données dans le graphe. Auth par clé API via l'en-tête X-Connector-Key.
  • Cerveau d'entreprise (/api/v1/octopia/memories) : mémoire sémantique partagée entre devs et agents (fait/préférence/contexte/insight), recherchable sémantiquement et rattachée aux entités du graphe (client, projet…). Auth OAuth2 Bearer (PAT, ex. via le device flow CLI) avec le scope adapté au verbe (read pour les lectures — y compris la recherche exposée en POST /memories/search — write pour les mutations).

Pour l'authentification, voir la page Authentification.

Octopia

Octopia Knowledge Graph API — ingestion de données externes via connecteurs

Ingérer des données externes dans le Knowledge Graph

Importe des entités et des relations dans le Knowledge Graph Octopia depuis un connecteur externe.

Authentification : via header X-Connector-Key (clé API du connecteur, pas OAuth2).

Workflow typique :

  1. Créer un connecteur via l'interface Octopia (qui génère une clé API)
  2. Envoyer les données à cet endpoint avec la clé dans le header
  3. Les entités sont créées ou mises à jour (upsert par nom)
  4. Les relations sont créées entre les entités

Types d'entités supportés : person, company, team, skill, tag, project, contract, product, service, location, event, role

Cas d'usage :

  • Synchronisation depuis un CRM (Salesforce, HubSpot)
  • Import depuis un ERP (SAP, Sage)
  • Enrichissement depuis des sources externes (API, CSV)
Authorizations:
ConnectorApiKey
Request Body schema: application/json
required
required
Array of objects

Liste des entités à créer ou mettre à jour (upsert par nom)

Array of objects

Liste des relations à créer entre entités

Responses

Request samples

Content type
application/json
Example
{
  • "entities": [
    ],
  • "relations": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "imported": 3,
  • "updated": 0,
  • "errors": [ ]
}

Mémoire

Cerveau d'entreprise : mémoire sémantique partagée entre devs et agents. Chaque mémoire porte son auteur (user_id), est recherchable sémantiquement par tous, et se rattache à des entités du graphe (client, projet…) via links — ces entités sont les points de convergence (documents hubdoc, mémoires…) qui rendent le graphe naviguable.

Lister les mémoires du cerveau d'entreprise

Authorizations:
OAuth2PasswordOAuth2AuthCode
query Parameters
memory_type
string
Enum: "fact" "preference" "context" "insight"
scope[type]
string

Type d'entité de rattachement (ex. client, project) — restreint la liste.

scope[name]
string

Nom de l'entité de rattachement.

per_page
integer [ 1 .. 200 ]
Default: 50
page
integer >= 1
Default: 1

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stocker une mémoire et la rattacher à des entités du graphe

Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema: application/json
required
content
required
string >= 30 characters

Fait atomique en langage naturel (≥ 30 caractères ; un contenu trop court ou bruité est rejeté par le quality gate en 422).

memory_type
string
Default: "context"
Enum: "fact" "preference" "context" "insight"
category
string
Enum: "professional" "personal" "project" "domain" "technical"
confidence
number <float> [ 0 .. 1 ]
Default: 0.8
tags
Array of strings
Array of objects (EntityLink)

Entités du graphe auxquelles rattacher la mémoire (client, projet…).

Responses

Request samples

Content type
application/json
{
  • "content": "Le client DSH utilise l'ERP Aareon Prem'Habitat pour ses signalements.",
  • "memory_type": "fact",
  • "category": "professional",
  • "confidence": 0.8,
  • "tags": [
    ],
  • "links": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content": "string",
  • "memory_type": "fact",
  • "category": "professional",
  • "confidence": 0.1,
  • "salience": 0.1,
  • "tags": [
    ],
  • "origin": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "similarity": 0.1,
  • "related_entities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "links": [
    ]
}

Détail d'une mémoire (avec ses entités liées)

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content": "string",
  • "memory_type": "fact",
  • "category": "professional",
  • "confidence": 0.1,
  • "salience": 0.1,
  • "tags": [
    ],
  • "origin": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "similarity": 0.1,
  • "related_entities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Oublier une mémoire (supprime le record et son nœud graphe)

Authorizations:
OAuth2PasswordOAuth2AuthCode
path Parameters
id
required
string <uuid>
Example: 019951a3-01b7-7eb9-88bb-f872a01ed886

Identifiant de la ressource

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "message": "Authentification requise"
}

Recherche sémantique dans le cerveau d'entreprise

Recherche sémantique (pgvector) sur tous les auteurs (mémoire commune), enrichie des entités liées du graphe. Optionnellement restreinte à une entité via scope.

Authorizations:
OAuth2PasswordOAuth2AuthCode
Request Body schema: application/json
required
query
required
string

Texte de recherche en langage naturel.

memory_type
string
Enum: "fact" "preference" "context" "insight"
limit
integer [ 1 .. 50 ]
Default: 5
object

Restreint la recherche aux mémoires liées à cette entité.

Responses

Request samples

Content type
application/json
{
  • "query": "quel ERP utilise DSH ?",
  • "memory_type": "fact",
  • "limit": 5,
  • "scope": {
    }
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "count": 0,
  • "results": [
    ]
}