rixl-go

README

rixl-go

Go client for the RIXL API.

Install

go get github.com/rixlhq/rixl-go

Requires Go 1.25.0+.

Quick start

package main

import (
    "context"
    "fmt"

    "github.com/rixlhq/rixl-go/sdk"
)

func main() {
    client, err := sdk.New("YOUR_RIXL_API_KEY")
    if err != nil {
        panic(err)
    }

    img, err := client.Images.GetImagesImageId(context.Background(), "PS5IMKoFLm")
    if err != nil {
        panic(err)
    }
    fmt.Println(*img.ID, *img.Width, *img.Height)
}

sdk.New(apiKey, opts...) returns a Client with three resource fields — client.Feeds, client.Images, client.Videos — each a typed client whose methods return parsed models and a Go error.

Configuration

client, err := sdk.New(apiKey,
    sdk.WithHTTPClient(myHTTPClient),  // custom timeouts, transport, etc.
    sdk.WithRequestEditor(addTracing), // mutate every outbound request
)

For bearer-token auth, pass an empty key and use WithBearer:

client, err := sdk.New("", sdk.WithBearer(token))

Feeds

import "github.com/rixlhq/rixl-go/sdk/feeds"

page, err := client.Feeds.GetFeedsFeedId(ctx, "FD4y3QB38S", &feeds.GetFeedsFeedIdParams{})
for _, post := range page.Data {
    fmt.Println(*post.ID)
}

post, err := client.Feeds.GetFeedsFeedIdPostId(ctx, "FD4y3QB38S", "PO9XQxWXQ")

Images

import "github.com/rixlhq/rixl-go/sdk/images"

list, err := client.Images.GetImages(ctx, nil)
img,  err := client.Images.GetImagesImageId(ctx, "PS5IMKoFLm")

// Delete returns the raw *http.Response (no JSON body to parse).
resp, err := client.Images.DeleteImagesImageId(ctx, "PS5IMKoFLm")

Upload (init → PUT bytes → complete):

import "github.com/rixlhq/rixl-go/sdk/models"

name, format := "photo.jpg", "jpeg"
init, err := client.Images.PostImagesUploadInit(ctx, models.InternalImagesHandlerUploadInitRequest{
    Name:   &name,
    Format: &format,
})
// PUT bytes to *init.PresignedURL

attached := false
done, err := client.Images.PostImagesUploadComplete(ctx, models.InternalImagesHandlerCompleteRequest{
    ImageID:         init.ImageID,
    AttachedToVideo: &attached,
})
fmt.Println(*done.ID)

Videos

import "github.com/rixlhq/rixl-go/sdk/models"

list,  err := client.Videos.GetVideos(ctx, nil)
video, err := client.Videos.GetVideosVideoId(ctx, "VI9VXQxWXQ")

Upload returns presigned URLs for both the video and a poster image:

posterFormat := "jpeg"
init, err := client.Videos.PostVideosUploadInit(ctx, models.VideoUploadInitRequest{
    FileName:    "clip.mp4",
    ImageFormat: &posterFormat,
})
// PUT to init.VideoPresignedURL and init.PosterPresignedURL

done, err := client.Videos.PostVideosUploadComplete(ctx, models.GithubComRixlhqAPIInternalVideosHandlerUploadCompleteRequest{
    VideoID: init.VideoID,
})
fmt.Println(*done.ID)

Pagination

List endpoints accept limit, offset, sort, order:

import "github.com/rixlhq/rixl-go/sdk/images"

limit, offset := 50, 0
for {
    page, err := client.Images.GetImages(ctx, &images.GetImagesParams{
        Limit: &limit, Offset: &offset,
    })
    if err != nil {
        return err
    }
    for _, img := range page.Data {
        fmt.Println(*img.ID)
    }
    if offset+len(page.Data) >= *page.Pagination.Total {
        break
    }
    offset += limit
}

Errors

API errors come back as a typed *ClientHttpError[E] carrying the HTTP status, raw body, and the parsed error response.

import (
    "errors"

    "github.com/rixlhq/rixl-go/sdk/images"
    "github.com/rixlhq/rixl-go/sdk/models"
)

img, err := client.Images.GetImagesImageId(ctx, "PS5IMKoFLm")
if err != nil {
    var apiErr *images.ClientHttpError[models.GithubComRixlhqAPIInternalErrorsErrorResponse]
    if errors.As(err, &apiErr) {
        fmt.Printf("HTTP %d: %s\n", apiErr.StatusCode, *apiErr.Body.Error)
    }
    return err
}

Each resource package (feeds, images, videos) defines its own ClientHttpError[E] — type-assert against the package whose method you called.

Examples

Runnable demos in examples/:

export RIXL_API_KEY=<key>
go run ./examples/basic/images
go run ./examples/advanced/videos

Regenerating the SDK

The SDK is generated by oapi-codegen-exp — the experimental fork that supports OpenAPI 3.1. Layout:

sdk/
├── models/    every component schema
├── runtime/   shared codegen helpers
├── feeds/     Client + SimpleClient for tag=Feeds
├── images/    same for Images
├── videos/    same for Videos
└── sdk.go     hand-written facade exposed as `sdk.New(...)`

oapi-codegen-exp is pinned in go.mod as a project tool — gen.sh invokes it via go tool oapi-codegen, no separate install needed.

./gen.sh

Per-package codegen configs live inline in gen.sh as heredocs.

Issues

github.com/rixlhq/rixl-go/issues