Doc Extract API

Port : 8000 | NodePort : 30002 | Repo : solyntek/djinn/services/djinn-doc-extract

Extraction de données structurées depuis factures, reçus, CV et pièces d'identité via OCR + LLM.

Endpoints

Méthode	Route	Description
GET	/health	Health check
GET	/v1/schemas	Schémas des types de documents supportés
POST	/v1/extract	Extraction depuis un fichier unique
POST	/v1/extract/batch	Extraction batch depuis plusieurs fichiers

Types de documents

Type	Données extraites
invoice	vendor, numéro, date, lignes, totaux, TVA, IBAN
receipt	vendor, date, lignes, totaux, mode de paiement
resume	nom, email, skills, expériences, diplômes, certifications
id_card	nom, date naissance, nationalité, numéro document

Exemple

Local (NodePort direct)Production (via Kong)

curl -X POST http://localhost:30002/v1/extract \
  -F "file=@cv.pdf" \
  -F "document_type=resume"

curl -X POST https://api.djinn.solyntek.io/v1/extract \
  -H "X-API-Key: your-api-key" \
  -F "file=@cv.pdf" \
  -F "document_type=resume"

{
  "document_type": "resume",
  "data": {
    "firstname": "Jean",
    "lastname": "Dupont",
    "skills": ["Python", "Go", "Docker"],
    "experiences": [{"company": "Acme", "title": "Senior Dev"}]
  },
  "confidence": 0.87
}

Référence interactive

Générée à chaque build depuis la spec versionnée openapi/doc-extract-v1.json (ADR-011) — aucune route documentée à la main.

Djinn Document Extract 0.2.0

Extraction de données structurées depuis factures, reçus, CVs et IDs

---

Endpoints

---

GET /health

Health

Description

Health check endpoint.

Responses

200 OK

application/json

{
    "status": "string",
    "version": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "status": {
            "type": "string",
            "title": "Status",
            "default": "ok"
        },
        "version": {
            "type": "string",
            "title": "Version",
            "default": "0.2.0"
        }
    },
    "type": "object",
    "title": "HealthResponse",
    "description": "Response model for the health check endpoint."
}

---

GET /v1/schemas

Schemas

Description

List all supported document schemas with their fields.

Input parameters

Parameter	In	Type	Default	Nullable	Description
X-API-Key	header			No
X-Internal-Service	header			No
X-Tenant-ID	header			No

Responses

200 OK422 Unprocessable Entity

application/json

[
    {
        "document_type": "string",
        "fields": [
            {
                "name": "string",
                "type": "string",
                "description": null
            }
        ]
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/SchemaInfo"
    },
    "title": "Response Schemas V1 Schemas Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /v1/extract

Extract

Description

Extract structured data from a single uploaded file.

Input parameters

Parameter	In	Type	Default	Nullable	Description
document_type	query			No
X-API-Key	header			No
X-Internal-Service	header			No
X-Tenant-ID	header			No

Request body

multipart/form-data

{
    "file": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File"
        }
    },
    "type": "object",
    "required": [
        "file"
    ],
    "title": "Body_extract_v1_extract_post"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "document_type": "invoice",
    "data": null,
    "text_source": null,
    "raw_text": "string",
    "confidence": 10.12,
    "field_confidences": [
        {
            "field": "string",
            "score": 10.12,
            "reason": null
        }
    ],
    "pii_detected": null,
    "error": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "document_type": {
            "$ref": "#/components/schemas/DocumentType"
        },
        "data": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/InvoiceData"
                },
                {
                    "$ref": "#/components/schemas/ReceiptData"
                },
                {
                    "$ref": "#/components/schemas/ResumeData"
                },
                {
                    "$ref": "#/components/schemas/IDCardData"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Data"
        },
        "text_source": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/TextSource"
                },
                {
                    "type": "null"
                }
            ]
        },
        "raw_text": {
            "type": "string",
            "title": "Raw Text"
        },
        "confidence": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Confidence"
        },
        "field_confidences": {
            "items": {
                "$ref": "#/components/schemas/FieldConfidence"
            },
            "type": "array",
            "title": "Field Confidences"
        },
        "pii_detected": {
            "anyOf": [
                {
                    "items": {
                        "additionalProperties": true,
                        "type": "object"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Pii Detected"
        },
        "error": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error"
        }
    },
    "type": "object",
    "required": [
        "document_type",
        "raw_text",
        "confidence"
    ],
    "title": "ExtractionResult"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /v1/extract/batch

Extract Batch

Description

Extract structured data from multiple uploaded files.

Input parameters

Parameter	In	Type	Default	Nullable	Description
document_type	query			No
X-API-Key	header			No
X-Internal-Service	header			No
X-Tenant-ID	header			No

Request body

multipart/form-data

{
    "files": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "files": {
            "items": {
                "type": "string",
                "contentMediaType": "application/octet-stream"
            },
            "type": "array",
            "title": "Files"
        }
    },
    "type": "object",
    "required": [
        "files"
    ],
    "title": "Body_extract_batch_v1_extract_batch_post"
}

Responses

200 OK422 Unprocessable Entity

application/json

[
    {
        "document_type": "invoice",
        "data": null,
        "text_source": null,
        "raw_text": "string",
        "confidence": 10.12,
        "field_confidences": [
            {
                "field": "string",
                "score": 10.12,
                "reason": null
            }
        ],
        "pii_detected": null,
        "error": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/ExtractionResult"
    },
    "title": "Response Extract Batch V1 Extract Batch Post"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

Schemas

Body_extract_batch_v1_extract_batch_post

Name	Type	Description
files	Array<string>

Body_extract_v1_extract_post

Name	Type	Description
file	string

Certification

Name	Type	Description
name
provider
year

Diploma

Name	Type	Description
degree
end_date
field_of_study
school
start_date

DocumentType

Type: string

Experience

Name	Type	Description
company
description
end_date		YYYY-MM, YYYY, or 'Present'
location
start_date		YYYY-MM or YYYY
title

ExtractionResult

Name	Type	Description
confidence	number
data
document_type	DocumentType
error
field_confidences	Array<FieldConfidence>
pii_detected
raw_text	string
text_source

FieldConfidence

Name	Type	Description
field	string
reason
score	number

HealthResponse

Name	Type	Description
status	string
version	string

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

IDCardData

Name	Type	Description
birth_date
birth_place
document_number
expiry_date
first_name
gender		M or F
issue_date
last_name
nationality

InvoiceData

Name	Type	Description
currency		ISO 4217 code (EUR, USD, ...)
due_date
invoice_date
invoice_number
line_items	Array<LineItem>
payment_method
payment_reference		IBAN or payment reference
subtotal
total_amount
vat_amount
vendor_address
vendor_name
vendor_tax_id		SIRET / tax ID

LineItem

Name	Type	Description
amount
description
quantity
unit_price
vat_rate

ReceiptData

Name	Type	Description
currency
line_items	Array<LineItem>
payment_method
receipt_date
subtotal
total_amount
vat_amount
vendor_address
vendor_name

ResumeData

Name	Type	Description
certifications	Array<Certification>
diplomas	Array<Diploma>
email
experiences	Array<Experience>
firstname
languages	Array<string>
lastname
linkedin
location
phone
skills	Array<string>

SchemaField

Name	Type	Description
description
name	string
type	string

SchemaInfo

Name	Type	Description
document_type	string
fields	Array<SchemaField>

TextSource

Type: string

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string