Skip to content
Forgecroft Docs

Go SDK Quickstart

Installation

Section titled “Installation”
Terminal window
go get github.com/forgecroft/forgecroft/sdk@latest

The SDK uses only the Go standard library — no external dependencies.

Creating a Client

Section titled “Creating a Client”
import "github.com/forgecroft/forgecroft/sdk"


client := sdk.New("https://api.forgecroft.com", "fc_live_...")

The client sends Authorization: Bearer <key> on every request. It uses a default 30-second HTTP timeout. You can customize the transport via client.HTTPClient.

Check Your Identity

Section titled “Check Your Identity”
resp, err := client.WhoAmI(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Org: %s  Role: %s  Scopes: %v\n", resp.OrgID, resp.OrgRole, resp.Scopes)

Ingest a Repository

Section titled “Ingest a Repository”

Ontologize reads a repository on the server filesystem and proposes graph nodes and edges — the system map a change is later evaluated against. Pass DryRun to preview without writing.

The request body carries a source object (kind, currently only "local_path", and ref, the absolute repository path on the server) and a mode ("delta" to add to the graph, or "bootstrap" to delete-then-insert):

{
  "source": { "kind": "local_path", "ref": "/abs/path/to/repo" },
  "mode": "delta"
}

The Go client mirrors that shape and returns the proposal count plus coverage notes:

res, err := client.Ontologize(ctx, input) // input built from the fields above
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Created %d proposals\n", res.ProposalsCreated)
for _, note := range res.CoverageNotes {
    fmt.Printf("coverage: %s — %s\n", note.Code, note.Message)
}

Approve or Reject a Proposal

Section titled “Approve or Reject a Proposal”

Proposals from an ingest enter a review queue. Approve one to add it to the live graph (Status: 2 approves, 3 rejects).

for _, id := range res.ProposalIDs {
    _, err := client.DecideProposal(ctx, id, sdk.DecideProposalInput{
        Status:    2, // approved
        DecidedBy: "you@example.com",
    })
    if err != nil {
        log.Fatal(err)
    }
}

Manage API Keys

Section titled “Manage API Keys”
// Create a project-scoped key for the CI gate
key, err := client.CreateAPIKey(ctx, sdk.APIKeyCreateRequest{
    Name:        "CI Gate",
    ScopeType:   "project",
    ScopeID:     "project-uuid",
    ActionScope: "read",
    Scopes:      []string{"evaluate:read", "resolve:read"},
})
// key.Key contains the raw value — store it securely


// Suspend a compromised key immediately
suspended := true
_, err = client.PatchAPIKey(ctx, keyID, sdk.APIKeyPatchRequest{
    Suspended: &suspended,
})


// List all keys for auditing
keys, err := client.ListAPIKeys(ctx)

Error Handling

Section titled “Error Handling”

API errors are returned as *sdk.APIError:

_, err := client.CreateAPIKey(ctx, req)
if err != nil {
    var apiErr *sdk.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case 403:
            log.Fatal("API key lacks permission")
        case 429:
            log.Fatal("Rate limited — back off and retry")
        }
    }
    log.Fatal(err)
}

SDK Coverage

Section titled “SDK Coverage”

The SDK currently covers authentication (WhoAmI), repository ingest (Ontologize), proposal decisions (DecideProposal), and API key management. For endpoints not yet in the SDK — evaluate, resolve, query, describe, diagnose, notifications — use standard net/http with Bearer token auth against the API reference.

Section titled “Related”