Upload and extract

Upload a source file, wait until yggy finishes extraction, then read the facts. This sample uses Q4 report.pdf in project 0xproject.

The samples read your key from the YGGY_API_KEY environment variable. Replace the host, organization id or slug, and project ID with values from your environment. Create a key as described in Authentication.

Every parameter and response field is in the Reference.

Upload the file

Send the file as multipart/form-data to the project upload route. A successful upload returns 202 and queues extraction.

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  --form "[email protected]" \
  --form "title=Q4 report.pdf" \
  "https://api.yggy.tech/api/v1/projects/0xproject/documents/upload"

A successful response has this form:

{
  "success": true,
  "documentId": "9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f",
  "internalId": "0x123",
  "invocationId": "inv_example",
  "status": "queued",
  "storagePath": "org_example/0xproject/9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f.pdf",
  "storageUrl": "https://files.example/9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f.pdf",
  "message": "Document queued for processing. Use GET /api/v1/documents/{id}/status/stream for real-time updates."
}

Use documentId in the later calls. The file is not searchable in the graph until extraction completes.

Wait for extraction

Poll document status until completed is true or failed is true. Prefer GET /api/v1/documents/{id}/status/stream when you can keep a connection open. A 429 response includes Retry-After in seconds.

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  "https://api.yggy.tech/api/v1/projects/0xproject/documents/9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f/status"

While extraction runs, a status payload looks like this:

{
  "documentId": "9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f",
  "status": "running",
  "completed": false,
  "failed": false,
  "progress": 40,
  "message": "Extracting facts"
}

When extraction succeeds, completed is true. If failed is true, inspect error and stop. If awaitingOntologyReview is true, extraction already finished; a vocabulary gap remains for a curator. The document is complete and the gap facts are in the graph.

Read the triples

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  "https://api.yggy.tech/api/v1/projects/0xproject/documents/9f3c1a2e-4b7d-4e11-9c22-0a1b2c3d4e5f/triples"

A successful response includes the extracted facts. This example has one supply relationship:

{
  "triples": [
    {
      "id": "0xtriple",
      "subject": "Acme Corp",
      "predicate": "supplies",
      "object": "Rotor Assembly",
      "evidence": ["Acme Corp supplies the Rotor Assembly for the Q4 line."]
    }
  ]
}

The response can contain more fields. Continue with Read extracted facts to list completed documents in a project.