Go SDK

The Go SDK needs Go 1.23 or newer. Every call takes a context.Context. The source is at github.com/yggy-tech/yggy-sdk-go.

Install

go get github.com/yggy-tech/[email protected]

Go modules install straight from the GitHub tag, so no registry is involved.

Authenticate

Create an API key in yggy under Developers → API keys and keep it in the YGGY_API_KEY environment variable. A key that belongs to one organization needs nothing else. A personal key can see several organizations, so name the one you want in the x-yggy-organization-id header, by id or slug, as the examples do. See Authentication for key types and permissions.

Make your first call

List the projects your key can see:

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  yggy "github.com/yggy-tech/yggy-sdk-go"
)

func main() {
  cfg := yggy.NewConfiguration()
  cfg.AddDefaultHeader("x-yggy-organization-id", "acme-corp")
  client := yggy.NewAPIClient(cfg)

  ctx := context.WithValue(context.Background(), yggy.ContextAPIKeys, map[string]yggy.APIKey{
    "apiKeyAuth": {Key: os.Getenv("YGGY_API_KEY")},
  })
  res, _, err := client.ProjectsAPI.ListProjects(ctx).Execute()
  if err != nil {
    log.Fatal(err)
  }
  for _, project := range res.Projects {
    fmt.Println(project.Name)
  }
}

Each group of operations is a field on the client, for example client.ProjectsAPI, client.DocumentsAPI and client.QueryAPI. A call builds a request, optional parameters are chained methods, and Execute() sends it. It returns the result, the *http.Response and an error.

Upload, wait and read the facts

This sample uploads Q4-report.pdf to project 0xproject, waits until extraction finishes, prints the extracted facts and asks a question. See Upload and extract for what each step returns.

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "time"

  yggy "github.com/yggy-tech/yggy-sdk-go"
)

func main() {
  cfg := yggy.NewConfiguration()
  cfg.AddDefaultHeader("x-yggy-organization-id", "acme-corp")
  client := yggy.NewAPIClient(cfg)
  ctx := context.WithValue(context.Background(), yggy.ContextAPIKeys, map[string]yggy.APIKey{
    "apiKeyAuth": {Key: os.Getenv("YGGY_API_KEY")},
  })
  projectID := "0xproject"

  file, err := os.Open("Q4-report.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()
  upload, _, err := client.DocumentsAPI.UploadDocument(ctx, projectID).File(file).Title("Q4 report.pdf").Execute()
  if err != nil {
    log.Fatal(err)
  }

  for {
    status, _, err := client.DocumentsAPI.GetDocumentStatus(ctx, projectID, upload.DocumentId).Execute()
    if err != nil {
      log.Fatal(err)
    }
    if status.Failed {
      log.Fatal("extraction failed")
    }
    if status.Completed {
      break
    }
    time.Sleep(2 * time.Second)
  }

  triples, _, err := client.DocumentsAPI.ListDocumentTriples(ctx, projectID, upload.DocumentId).Execute()
  if err != nil {
    log.Fatal(err)
  }
  for _, t := range triples.Triples {
    fmt.Println(t.Subject, t.Predicate, t.Object)
  }

  answer, _, err := client.QueryAPI.QueryProject(ctx, projectID).
    QueryProjectRequest(*yggy.NewQueryProjectRequest("Which contracts renew in Q1?")).Execute()
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(answer.Answer)
}

Handle errors

A call that gets an error status returns a non-nil error, and the second return value holds the *http.Response, so check StatusCode first. The error is a *yggy.GenericOpenAPIError, whose Body() is the raw JSON with the error code.

_, httpRes, err := client.ProjectsAPI.ListProjects(ctx).Execute()
if err != nil {
  var apiErr *yggy.GenericOpenAPIError
  if errors.As(err, &apiErr) && httpRes != nil {
    log.Printf("%d %s", httpRes.StatusCode, apiErr.Body())
  }
  return err
}

See Errors and rate limits for the codes and for 429 handling. Honour the Retry-After header before you retry.

Next steps

• Reference for every operation and field.
• Authentication for key types and permissions.
• Webhooks to react to events instead of polling.