cursor

package module
v0.0.0-...-81a6472 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 11, 2026 License: MIT Imports: 7 Imported by: 0

README

cursor-go (alpha)

Unofficial Go SDK for the Cursor Cloud Agents API.

This SDK is alpha and in progress. APIs, types, and behavior may change without notice.

Quick Start: New Project

# Create a new directory
mkdir my-cursor-app
cd my-cursor-app

# Initialize Go module
go mod init github.com/your-org/my-cursor-app

# Add cursor-go dependency
go get github.com/PippaOS/cursor-go@latest

# Create main.go (see Usage below)

Install

go get github.com/PippaOS/cursor-go@latest

Usage

package main

import (
	"context"
	"log"
	"os"

	"github.com/PippaOS/cursor-go"
)

func main() {
	ctx := context.Background()

	c, err := cursor.NewClient(os.Getenv("CURSOR_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	models, err := c.Models.List(ctx)
	if err != nil {
		log.Fatal(err)
	}
	log.Println(models)
}

Regenerating from OpenAPI

Generated code lives in internal/oapi/ and is produced from openapi/0.1.0.yml.

go generate ./...

Issues / sharp edges (current)

  • OpenAPI response shapes are inlined, so oapi-codegen generates some anonymous structs (harder to reuse / map cleanly).
  • Spec inconsistencies:
    • status is constrained to only "CREATING" in the create response, but other endpoints use a wider enum.
    • Some fields flip between required vs optional across endpoints (e.g. source.repository).
  • The public wrapper API is intentionally small right now; more polish (iterators, retries, richer errors) is still pending.

Documentation

Index

Constants

View Source
const DefaultBaseURL = "https://api.cursor.com"

DefaultBaseURL is the default Cursor API base URL.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Code       string
	Message    string
	Body       []byte
}

APIError represents a non-2xx response from the Cursor API.

func (*APIError) Error

func (e *APIError) Error() string

type APIKeyInfo

type APIKeyInfo struct {
	APIKeyName string
	CreatedAt  time.Time
	UserEmail  *string
}

APIKeyInfo is returned by the /v0/me endpoint.

type Agent

type Agent struct {
	ID        string
	Name      string
	Status    AgentStatus
	Source    AgentSource
	Target    AgentTarget
	Summary   *string
	CreatedAt time.Time
}

Agent is a cloud agent instance.

type AgentSource

type AgentSource struct {
	Repository string
	Ref        *string
}

type AgentStatus

type AgentStatus string
const (
	AgentStatusCreating AgentStatus = "CREATING"
	AgentStatusRunning  AgentStatus = "RUNNING"
	AgentStatusFinished AgentStatus = "FINISHED"
	AgentStatusError    AgentStatus = "ERROR"
	AgentStatusExpired  AgentStatus = "EXPIRED"
)

type AgentTarget

type AgentTarget struct {
	URL                   string
	BranchName            *string
	PRURL                 *string
	AutoCreatePR          *bool
	OpenAsCursorGitHubApp *bool
	SkipReviewerRequest   *bool
}

type AgentsPage

type AgentsPage struct {
	Agents     []Agent
	NextCursor *string
}

AgentsPage is a single page of agents from List.

type AgentsService

type AgentsService struct {
	// contains filtered or unexported fields
}

func (*AgentsService) AddFollowup

func (s *AgentsService) AddFollowup(ctx context.Context, id string, req FollowupRequest) (string, error)

AddFollowup adds a follow-up instruction to an existing agent and returns the agent ID.

func (*AgentsService) Conversation

func (s *AgentsService) Conversation(ctx context.Context, id string) (*Conversation, error)

Conversation returns the agent conversation history.

func (*AgentsService) Create

func (s *AgentsService) Create(ctx context.Context, req CreateAgentRequest) (*Agent, error)

Create launches a new agent.

func (*AgentsService) Delete

func (s *AgentsService) Delete(ctx context.Context, id string) (string, error)

Delete permanently deletes an agent and returns the deleted agent ID.

func (*AgentsService) Get

func (s *AgentsService) Get(ctx context.Context, id string) (*Agent, error)

Get returns details for a single agent.

func (*AgentsService) List

List returns a single page of agents.

func (*AgentsService) Stop

func (s *AgentsService) Stop(ctx context.Context, id string) (string, error)

Stop stops a running agent and returns the agent ID.

func (*AgentsService) Wait

func (s *AgentsService) Wait(ctx context.Context, id string, opts WaitOptions) (*Agent, error)

Wait polls Get until the agent reaches a terminal state (FINISHED, ERROR, EXPIRED), or the context is cancelled.

type Client

type Client struct {
	Agents       *AgentsService
	Me           *MeService
	Models       *ModelsService
	Repositories *RepositoriesService
	// contains filtered or unexported fields
}

Client is the public Cursor Cloud Agents API client.

It wraps the generated OpenAPI client in internal/oapi, keeping generated code as an implementation detail while providing a stable, ergonomic API surface.

func NewClient

func NewClient(apiKey string, opts ...ClientOption) (*Client, error)

NewClient creates a new Cursor API client using a Bearer API key.

type ClientOption

type ClientOption func(*clientOptions) error

ClientOption configures a Client.

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL overrides the default API base URL.

func WithHTTPClient

func WithHTTPClient(httpClient HTTPDoer) ClientOption

WithHTTPClient overrides the underlying HTTP client used for requests.

func WithRequestEditor

func WithRequestEditor(editor RequestEditor) ClientOption

WithRequestEditor registers a function to mutate outgoing requests.

func WithUserAgent

func WithUserAgent(userAgent string) ClientOption

WithUserAgent sets a custom User-Agent header on all requests.

type Conversation

type Conversation struct {
	AgentID  string
	Messages []ConversationMessage
}

Conversation is the conversation history for an agent.

type ConversationMessage

type ConversationMessage struct {
	ID   string
	Type ConversationMessageType
	Text string
}

type ConversationMessageType

type ConversationMessageType string
const (
	ConversationMessageTypeUser      ConversationMessageType = "user_message"
	ConversationMessageTypeAssistant ConversationMessageType = "assistant_message"
)

type CreateAgentRequest

type CreateAgentRequest struct {
	Prompt  Prompt
	Model   *string
	Source  AgentSource
	Target  *CreateAgentTarget
	Webhook *Webhook
}

CreateAgentRequest launches an agent.

type CreateAgentTarget

type CreateAgentTarget struct {
	AutoCreatePR          *bool
	OpenAsCursorGitHubApp *bool
	SkipReviewerRequest   *bool
	BranchName            *string
}

type FollowupRequest

type FollowupRequest struct {
	Prompt Prompt
}

FollowupRequest adds a follow-up prompt to an existing agent.

type HTTPDoer

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer is implemented by *http.Client and compatible HTTP clients.

type Image

type Image struct {
	Data      string
	Dimension *ImageDimension
}

Image is base64-encoded image data with optional dimensions.

type ImageDimension

type ImageDimension struct {
	Width  int
	Height int
}

ImageDimension describes an image's size in pixels.

type ListAgentsOptions

type ListAgentsOptions struct {
	Limit  *int
	Cursor *string
}

ListAgentsOptions controls pagination for listing agents.

type MeService

type MeService struct {
	// contains filtered or unexported fields
}

func (*MeService) Get

func (s *MeService) Get(ctx context.Context) (*APIKeyInfo, error)

Get returns information about the API key being used for authentication.

type ModelList

type ModelList struct {
	Models []string
}

ModelList is returned by the /v0/models endpoint.

type ModelsService

type ModelsService struct {
	// contains filtered or unexported fields
}

func (*ModelsService) List

func (s *ModelsService) List(ctx context.Context) ([]string, error)

List returns the recommended models for cloud agents.

type Prompt

type Prompt struct {
	Text   string
	Images []Image
}

Prompt is an instruction to the agent.

type RepositoriesService

type RepositoriesService struct {
	// contains filtered or unexported fields
}

func (*RepositoriesService) List

List returns GitHub repositories accessible to the authenticated user.

type Repository

type Repository struct {
	Owner string
	Name  string
	URL   string
}

Repository is returned by the /v0/repositories endpoint.

type RequestEditor

type RequestEditor func(ctx context.Context, req *http.Request) error

RequestEditor can mutate outgoing HTTP requests.

type WaitOptions

type WaitOptions struct {
	PollInterval time.Duration
}

type Webhook

type Webhook struct {
	URL    string
	Secret *string
}

Directories

Path Synopsis
internal
oapi
Package oapi provides primitives to interact with the openapi HTTP API.
Package oapi provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL