openaiorgs

package module
v0.7.1 Latest Latest
Warning

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

Go to latest
Published: Dec 2, 2025 License: MIT Imports: 10 Imported by: 0

README

openai-orgs - CLI for OpenAI Platform Management API

codecov

openai-orgs is a comprehensive command-line interface (CLI) tool and API client for managing OpenAI Platform Administration APIs. It provides comprehensive management capabilities for OpenAI organizations including projects, users, API keys, service accounts, certificates, audit logs, and more. The project also includes a Model Context Protocol (MCP) server for AI assistant integration.

Installation

CLI Tool

To install openai-orgs, make sure you have Go installed on your system, then run:

go install github.com/klauern/openai-orgs/cmd/openai-orgs@latest
MCP Server

To install the MCP server:

go install github.com/klauern/openai-orgs/cmd/mcp@latest
Development Setup

For development, you can use the included Task runner:

# Install Task if you don't have it
go install github.com/go-task/task/v3/cmd/task@latest

# Build the CLI
task build

# Build the MCP server
task mcp:build

# Run tests
task test

Configuration

Before using openai-orgs, you need to set up your OpenAI API key:

  1. Log in to your OpenAI account at https://platform.openai.com/
  2. Navigate to the API keys section
  3. Create a new API key
  4. Set the API key as an environment variable:
export OPENAI_API_KEY=your_api_key_here

Usage

openai-orgs uses subcommands to organize its functionality. Here are the main commands:

Organization Level Commands
  • audit-logs: Manage audit logs
  • invites: Manage organization invites
  • users: Manage organization users
  • admin-api-keys: Manage organization admin API keys
  • certificates: Manage organization certificates (mutual TLS)
Project Level Commands
  • projects: Manage organization projects
  • project-users: Manage project users
  • project-service-accounts: Manage project service accounts
  • project-api-keys: Manage project API keys
  • project-rate-limits: Manage project rate limits
  • project-certificates: Manage project certificates
Output Formats

All commands support multiple output formats via the --output flag:

  • pretty (default): Human-readable formatted output
  • json: JSON format
  • jsonl: JSON Lines format

To see available subcommands and options for each command, use the --help flag:

openai-orgs --help
openai-orgs <command> --help
Examples
  1. List all users in the organization:
openai-orgs users list
  1. Create a new project:
openai-orgs projects create --name "My New Project"
  1. List project API keys with JSON output:
openai-orgs project-api-keys list --project-id <project_id> --output json
  1. Create an invite:
openai-orgs invites create --email [email protected] --role member
  1. Manage certificates for mutual TLS:
openai-orgs certificates list
openai-orgs certificates create --cert-file ./cert.pem
  1. View audit logs:
openai-orgs audit-logs list --limit 10

MCP Server

The project includes a Model Context Protocol (MCP) server that provides AI assistants with tools and resources for managing OpenAI organizations.

Running the MCP Server
# Run the MCP server
mcp

# For development with debugging
task mcp:dev
MCP Features
  • Tools: Complete set of tools for all OpenAI organization and project management operations
  • Resources: Dynamic resource templates and subscription management
  • Type Safety: Reflection-based parameter validation
  • Integration: Works with Claude Desktop and other MCP-compatible AI assistants
MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "openai-orgs": {
      "command": "mcp",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Default Settings

  • The CLI uses the OpenAI API base URL: https://api.openai.com/v1
  • Authentication is handled using the OPENAI_API_KEY environment variable
  • List commands typically have optional --limit and --after flags to control pagination
  • Conservative retry strategy: 20 retries, 5-second wait, max 5-minute backoff

Error Handling

If an error occurs during command execution, the CLI will display an error message and exit with a non-zero status code.

Contributing

Contributions to openai-orgs are welcome! Please submit issues and pull requests on the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package openaiorgs provides a Go client for interacting with the OpenAI Organizations API.

The client handles authentication, rate limiting, and provides type-safe methods for all API operations. It supports managing organization resources such as users, projects, API keys, and service accounts.

Basic Usage:

client := openaiorgs.NewClient("", "your-api-key")
projects, err := client.ListProjects(10, "", false)
if err != nil {
	log.Fatal(err)
}

The package is organized into several main components:

Core Client:

  • API client with built-in retries and rate limiting
  • Generic request/response handling
  • Pagination support for list operations

Authentication & Users:

  • Organization API key management
  • User management (invite, modify roles, remove)
  • Organization invitations

Project Management:

  • Project creation and configuration
  • Project user management
  • Project-specific API keys
  • Rate limit configuration
  • Service account management

Usage & Audit:

  • Usage tracking and reporting
  • Audit logging
  • Administrative operations

Each component provides a set of methods for interacting with the corresponding API endpoints. All operations use strong typing and follow consistent patterns for error handling and response processing.

For detailed examples and documentation of specific types and methods, see the relevant type and function documentation.

Package openaiorgs implements a client for managing OpenAI organization resources. It provides methods for managing projects, users, API keys, and other organizational aspects of OpenAI accounts.

Index

Constants

View Source
const (
	// OrganizationCertificatesEndpoint is the base endpoint for organization certificate operations.
	OrganizationCertificatesEndpoint = "/organization/certificates"
	// OrganizationCertificateActivateEndpoint is the endpoint for bulk certificate activation.
	OrganizationCertificateActivateEndpoint = "/organization/certificates/activate"
	// OrganizationCertificateDeactivateEndpoint is the endpoint for bulk certificate deactivation.
	OrganizationCertificateDeactivateEndpoint = "/organization/certificates/deactivate"
	// ProjectCertificatesEndpoint is the base endpoint for project certificate operations.
	// Use with fmt.Sprintf to include the project ID: fmt.Sprintf(ProjectCertificatesEndpoint, projectID)
	ProjectCertificatesEndpoint = "/organization/projects/%s/certificates"
	// ProjectCertificateActivateEndpoint is the endpoint for project certificate activation.
	// Use with fmt.Sprintf to include the project ID: fmt.Sprintf(ProjectCertificateActivateEndpoint, projectID)
	ProjectCertificateActivateEndpoint = "/organization/projects/%s/certificates/activate"
	// ProjectCertificateDeactivateEndpoint is the endpoint for project certificate deactivation.
	// Use with fmt.Sprintf to include the project ID: fmt.Sprintf(ProjectCertificateDeactivateEndpoint, projectID)
	ProjectCertificateDeactivateEndpoint = "/organization/projects/%s/certificates/deactivate"
)

Certificate API endpoint constants

View Source
const AdminAPIKeysEndpoint = "/organization/admin_api_keys"

AdminAPIKeysEndpoint is the base endpoint for organization API key operations.

View Source
const AuditLogsListEndpoint = "/organization/audit_logs"
View Source
const DefaultBaseURL = "https://api.openai.com/v1"

DefaultBaseURL is the default endpoint for the OpenAI Organizations API.

View Source
const InviteListEndpoint = "/organization/invites"

InviteListEndpoint is the base endpoint for invitation management operations.

View Source
const ProjectApiKeysListEndpoint = "/organization/projects/%s/api_keys"

ProjectApiKeysListEndpoint specifies the API endpoint path for project API key operations.

View Source
const ProjectServiceAccountsListEndpoint = "/organization/projects/%s/service_accounts"

ProjectServiceAccountsListEndpoint is the base endpoint template for service account management. The %s placeholder must be filled with the project ID for all requests.

View Source
const ProjectUsersListEndpoint = "/organization/projects/%s/users"

ProjectUsersListEndpoint is the base endpoint template for project user management. The %s placeholder must be filled with the project ID for all requests.

View Source
const ProjectsListEndpoint = "/organization/projects"

ProjectsListEndpoint is the base endpoint for project management operations. All project-related API requests are made relative to this path.

View Source
const UsersListEndpoint = "/organization/users"

UsersListEndpoint is the base endpoint for user management operations.

Variables

This section is empty.

Functions

func Delete

func Delete[T any](client *resty.Client, endpoint string) error

Delete makes a DELETE request to remove a resource. It returns an error if the request fails or returns a non-2xx status code.

func GetSingle

func GetSingle[T any](client *resty.Client, endpoint string) (*T, error)

GetSingle makes a GET request to retrieve a single resource of type T. It handles JSON unmarshaling and error wrapping. Returns a pointer to the resource and any error encountered.

func Post

func Post[T any](client *resty.Client, endpoint string, body any) (*T, error)

Post makes a POST request to create a new resource of type T. It handles JSON marshaling of the request body and unmarshaling of the response. Returns a pointer to the created resource and any error encountered.

Types

type APIKeyActor added in v0.2.11

type APIKeyActor struct {
	Type string    `json:"type"`
	User AuditUser `json:"user"`
}

APIKeyActor represents API key information in the actor field

type APIKeyCreated

type APIKeyCreated struct {
	ID   string `json:"id"`
	Data struct {
		Scopes []string `json:"scopes"`
	} `json:"data"`
}

Event types and their corresponding payload structures

type APIKeyDeleted

type APIKeyDeleted struct {
	ID string `json:"id"`
}

type APIKeyUpdated added in v0.2.11

type APIKeyUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		Scopes []string `json:"scopes"`
	} `json:"changes_requested"`
}

type Actor

type Actor struct {
	Type    string       `json:"type"` // "session" or "api_key"
	Session *Session     `json:"session,omitempty"`
	APIKey  *APIKeyActor `json:"api_key,omitempty"`
}

Actor represents the entity performing the action

type AdminAPIKey added in v0.3.0

type AdminAPIKey struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`
	// ID is the unique identifier for this API key.
	ID string `json:"id"`
	// Name is a human-readable identifier for the API key.
	Name string `json:"name"`
	// RedactedValue is a partially hidden version of the API key for display purposes.
	RedactedValue string `json:"redacted_value"`
	// CreatedAt is the timestamp when this API key was created.
	CreatedAt UnixSeconds `json:"created_at"`
	// LastUsedAt is the timestamp when this API key was last used.
	LastUsedAt UnixSeconds `json:"last_used_at"`
	// Scopes define the permissions granted to this API key.
	Scopes []string `json:"scopes"`
}

AdminAPIKey represents an organization-level API key with its associated metadata. These keys provide administrative access to organization resources and operations.

func (*AdminAPIKey) String added in v0.3.1

func (ak *AdminAPIKey) String() string

String returns a human-readable string representation of the AdminAPIKey. It includes the key's ID, name, and a comma-separated list of scopes if any exist.

type AudioSpeechesUsage added in v0.3.1

type AudioSpeechesUsage struct {
	// Characters is the number of text characters processed.
	Characters int `json:"characters"`

	// Model identifies which text-to-speech model was used.
	Model string `json:"model"`
}

AudioSpeechesUsage represents the usage details for a text-to-speech request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeAudioSpeeches.

type AudioSpeechesUsageBucket added in v0.3.1

type AudioSpeechesUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed audio speeches usage data.
	Results []AudioSpeechesUsageResult `json:"results"`
}

AudioSpeechesUsageBucket represents a time-based bucket of audio speeches usage data. Each bucket contains aggregated statistics about text-to-speech API usage.

type AudioSpeechesUsageResponse added in v0.3.1

type AudioSpeechesUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of audio speeches usage buckets.
	Data []AudioSpeechesUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

AudioSpeechesUsageResponse represents the response from the audio speeches usage endpoint. This provides detailed statistics about text-to-speech API usage.

type AudioSpeechesUsageResult added in v0.3.1

type AudioSpeechesUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Characters is the number of text characters processed.
	Characters int `json:"characters"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which text-to-speech model was used.
	Model string `json:"model"`
}

AudioSpeechesUsageResult represents a single audio speeches usage record. This provides detailed information about text-to-speech operations, including character counts and request statistics.

type AudioTranscriptionsUsage added in v0.3.1

type AudioTranscriptionsUsage struct {
	// Seconds is the duration of audio processed.
	Seconds int `json:"seconds"`

	// Model identifies which speech-to-text model was used.
	Model string `json:"model"`
}

AudioTranscriptionsUsage represents the usage details for a speech-to-text request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeAudioTranscriptions.

type AudioTranscriptionsUsageBucket added in v0.3.1

type AudioTranscriptionsUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed audio transcriptions usage data.
	Results []AudioTranscriptionsUsageResult `json:"results"`
}

AudioTranscriptionsUsageBucket represents a time-based bucket of audio transcriptions usage data. Each bucket contains aggregated statistics about speech-to-text API usage.

type AudioTranscriptionsUsageResponse added in v0.3.1

type AudioTranscriptionsUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of audio transcriptions usage buckets.
	Data []AudioTranscriptionsUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

AudioTranscriptionsUsageResponse represents the response from the audio transcriptions usage endpoint. This provides detailed statistics about speech-to-text API usage.

type AudioTranscriptionsUsageResult added in v0.3.1

type AudioTranscriptionsUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Seconds is the duration of audio processed.
	Seconds int `json:"seconds"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which speech-to-text model was used.
	Model string `json:"model"`
}

AudioTranscriptionsUsageResult represents a single audio transcriptions usage record. This provides detailed information about speech-to-text operations, including audio duration and request statistics.

type AuditLog

type AuditLog struct {
	Object      string        `json:"object,omitempty"`
	ID          string        `json:"id"`
	Type        string        `json:"type"`
	EffectiveAt UnixSeconds   `json:"effective_at"`
	Project     *AuditProject `json:"project,omitempty"`
	Actor       Actor         `json:"actor"`
	Details     any           `json:"-"` // This will be unmarshaled based on Type
}

AuditLog represents the main audit log object

func (AuditLog) MarshalJSON added in v0.7.0

func (al AuditLog) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler to properly serialize the AuditLog including the event-specific details under the dynamic key (e.g., "invite.deleted")

func (*AuditLog) String added in v0.3.1

func (al *AuditLog) String() string

String returns a human-readable string representation of the AuditLog

func (*AuditLog) UnmarshalJSON added in v0.2.11

func (a *AuditLog) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the event-specific details using dynamic keys. The OpenAI API returns event details under a key matching the event type (e.g., "invite.deleted": {...}) rather than a static "details" key.

type AuditLogListParams

type AuditLogListParams struct {
	EffectiveAt *EffectiveAt `json:"effective_at,omitempty"`
	ProjectIDs  []string     `json:"project_ids,omitempty"`
	EventTypes  []string     `json:"event_types,omitempty"`
	ActorIDs    []string     `json:"actor_ids,omitempty"`
	ActorEmails []string     `json:"actor_emails,omitempty"`
	ResourceIDs []string     `json:"resource_ids,omitempty"`
	Limit       int          `json:"limit,omitempty"`
	After       string       `json:"after,omitempty"`
	Before      string       `json:"before,omitempty"`
}

AuditLogListParams represents the query parameters for listing audit logs

type AuditLogListResponse added in v0.2.11

type AuditLogListResponse struct {
	Object  string     `json:"object"`
	Data    []AuditLog `json:"data"`
	FirstID string     `json:"first_id"`
	LastID  string     `json:"last_id"`
	HasMore bool       `json:"has_more"`
}

AuditLogListResponse represents the paginated response from the audit logs endpoint

type AuditProject added in v0.2.11

type AuditProject struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

AuditProject represents project information in audit logs

type AuditUser added in v0.2.11

type AuditUser struct {
	ID    string `json:"id"`
	Email string `json:"email"`
}

AuditUser represents user information in audit logs

type BaseUsageResponse added in v0.3.1

type BaseUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of usage buckets.
	Data []UsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

BaseUsageResponse represents the common structure for new usage endpoints. This is the base type that type-specific responses embed and extend.

type Certificate added in v0.6.0

type Certificate struct {
	// Object identifies the type of this resource.
	// This varies based on context: "certificate", "organization.certificate", or "organization.project.certificate"
	Object string `json:"object"`
	// ID is the unique identifier for this certificate.
	ID string `json:"id"`
	// Name is the human-readable identifier for the certificate.
	Name string `json:"name"`
	// Active indicates whether the certificate is currently active.
	// This field is only present in list operations.
	Active *bool `json:"active,omitempty"`
	// CreatedAt is the timestamp when this certificate was created.
	CreatedAt UnixSeconds `json:"created_at"`
	// CertificateDetails contains validity information and optionally the certificate content.
	CertificateDetails CertificateDetails `json:"certificate_details"`
}

Certificate represents a mutual TLS certificate within an OpenAI organization. Certificates can be used for organization-level or project-level authentication.

func (*Certificate) String added in v0.6.0

func (c *Certificate) String() string

String returns a human-readable string representation of the Certificate. It includes basic metadata and certificate validity information.

type CertificateActivationResponse added in v0.6.0

type CertificateActivationResponse struct {
	// Object identifies the type of this response.
	Object string `json:"object"`
	// Success indicates whether the bulk operation completed successfully.
	Success bool `json:"success"`
}

CertificateActivationResponse represents the response from bulk certificate activation/deactivation operations.

type CertificateDeletedResponse added in v0.6.0

type CertificateDeletedResponse struct {
	// Object identifies the type of this response.
	Object string `json:"object"`
	// ID is the identifier of the deleted certificate.
	ID string `json:"id"`
	// Deleted indicates whether the certificate was successfully deleted.
	Deleted bool `json:"deleted"`
}

CertificateDeletedResponse represents the response from certificate deletion operations.

type CertificateDetails added in v0.6.0

type CertificateDetails struct {
	// ValidAt is the timestamp when this certificate becomes valid.
	ValidAt UnixSeconds `json:"valid_at"`
	// ExpiresAt is the timestamp when this certificate expires.
	ExpiresAt UnixSeconds `json:"expires_at"`
	// Content contains the PEM-encoded certificate content.
	// This field is only present when the include=content query parameter is used.
	Content *string `json:"content,omitempty"`
}

CertificateDetails contains the validity period and optional content of a certificate.

type Client

type Client struct {

	// BaseURL is the base endpoint for API requests.
	BaseURL string
	// contains filtered or unexported fields
}

Client represents an OpenAI Organizations API client. It handles authentication, request retries, and provides methods for interacting with the API.

func NewClient

func NewClient(baseURL, token string) *Client

NewClient creates a new OpenAI Organizations API client. It configures the client with the provided base URL and authentication token. If baseURL is empty, DefaultBaseURL is used.

func (*Client) ActivateOrganizationCertificates added in v0.6.0

func (c *Client) ActivateOrganizationCertificates(certificateIDs []string) (*CertificateActivationResponse, error)

ActivateOrganizationCertificates activates multiple certificates at the organization level. This is a bulk operation that atomically activates all specified certificates. All certificates must exist and be owned by the organization.

Parameters:

  • certificateIDs: List of certificate IDs to activate

Returns a CertificateActivationResponse indicating success or failure. If any certificate fails to activate, the entire operation is rolled back.

func (*Client) ActivateProjectCertificates added in v0.6.0

func (c *Client) ActivateProjectCertificates(projectID string, certificateIDs []string) (*CertificateActivationResponse, error)

ActivateProjectCertificates activates multiple certificates for a specific project. This is a bulk operation that atomically activates all specified certificates for the project. All certificates must exist and be accessible to the project.

Parameters:

  • projectID: The unique identifier of the project
  • certificateIDs: List of certificate IDs to activate for the project

Returns a CertificateActivationResponse indicating success or failure. If any certificate fails to activate, the entire operation is rolled back.

func (*Client) ArchiveProject

func (c *Client) ArchiveProject(id string) (*Project, error)

ArchiveProject moves a project to an archived state. Archived projects retain their data but cannot be modified or used for new operations. This operation cannot be undone through the API.

Parameters:

  • id: The unique identifier of the project to archive

Returns the updated Project object or an error if archiving fails. Returns an error if the project is already archived or if the caller lacks permission.

func (*Client) CreateAdminAPIKey added in v0.3.0

func (c *Client) CreateAdminAPIKey(name string, scopes []string) (*AdminAPIKey, error)

CreateAdminAPIKey creates a new organization API key.

Parameters:

  • name: A human-readable name for the API key
  • scopes: List of permission scopes to grant to the key

Returns the newly created AdminAPIKey or an error if creation fails. Note: The full API key value is only returned once upon creation.

func (*Client) CreateInvite

func (c *Client) CreateInvite(email string, role string) (*Invite, error)

CreateInvite sends a new invitation to join the organization.

Parameters:

  • email: The email address of the user to invite
  • role: The role to assign to the user upon acceptance

Returns the created Invite object or an error if creation fails.

func (*Client) CreateProject

func (c *Client) CreateProject(name string) (*Project, error)

CreateProject creates a new project in the organization. New projects are created in an active state and can be used immediately. The project name must be unique within the organization.

Parameters:

  • name: The human-readable name for the new project (must be unique)

Returns the created Project object or an error if creation fails. Common errors include duplicate project names or reaching project limits.

func (*Client) CreateProjectServiceAccount

func (c *Client) CreateProjectServiceAccount(projectID string, name string) (*ProjectServiceAccount, error)

CreateProjectServiceAccount creates a new service account in a project. The service account is created with a default role and an optional API key.

Parameters:

  • projectID: The unique identifier of the project to create the service account in
  • name: The human-readable name for the service account

Returns the created ProjectServiceAccount object or an error if creation fails. If successful, the response includes the API key value which should be stored securely as it cannot be retrieved later.

func (*Client) CreateProjectUser

func (c *Client) CreateProjectUser(projectID string, userID string, role string) (*ProjectUser, error)

CreateProjectUser adds a user to a project with a specified role. The user must already be a member of the organization.

Parameters:

  • projectID: The unique identifier of the project to add the user to
  • userID: The unique identifier of the user to add
  • role: The role to assign to the user (must be a valid RoleType)

Returns the created ProjectUser object or an error if the operation fails. Common errors include invalid roles, duplicate users, or insufficient permissions.

func (*Client) DeactivateOrganizationCertificates added in v0.6.0

func (c *Client) DeactivateOrganizationCertificates(certificateIDs []string) (*CertificateActivationResponse, error)

DeactivateOrganizationCertificates deactivates multiple certificates at the organization level. This is a bulk operation that atomically deactivates all specified certificates. All certificates must exist and be owned by the organization.

Parameters:

  • certificateIDs: List of certificate IDs to deactivate

Returns a CertificateActivationResponse indicating success or failure. If any certificate fails to deactivate, the entire operation is rolled back.

func (*Client) DeactivateProjectCertificates added in v0.6.0

func (c *Client) DeactivateProjectCertificates(projectID string, certificateIDs []string) (*CertificateActivationResponse, error)

DeactivateProjectCertificates deactivates multiple certificates for a specific project. This is a bulk operation that atomically deactivates all specified certificates for the project. All certificates must exist and be accessible to the project.

Parameters:

  • projectID: The unique identifier of the project
  • certificateIDs: List of certificate IDs to deactivate for the project

Returns a CertificateActivationResponse indicating success or failure. If any certificate fails to deactivate, the entire operation is rolled back.

func (*Client) DeleteAdminAPIKey added in v0.3.0

func (c *Client) DeleteAdminAPIKey(apiKeyID string) error

DeleteAdminAPIKey permanently removes an organization API key.

Parameters:

  • apiKeyID: The unique identifier of the API key to delete

Returns an error if deletion fails or nil on success.

func (*Client) DeleteCertificate added in v0.6.0

func (c *Client) DeleteCertificate(certificateID string) (*CertificateDeletedResponse, error)

DeleteCertificate removes a certificate from the organization. Deleted certificates cannot be recovered and will be immediately deactivated if they were active. This operation cannot be undone.

Parameters:

  • certificateID: The unique identifier of the certificate to delete

Returns a CertificateDeletedResponse confirming the deletion or an error if deletion fails. Returns an error if the certificate doesn't exist or if the caller lacks permission.

func (*Client) DeleteInvite

func (c *Client) DeleteInvite(id string) error

DeleteInvite cancels a pending invitation.

Parameters:

  • id: The unique identifier of the invitation to delete

Returns an error if deletion fails or nil on success.

func (*Client) DeleteProjectApiKey

func (c *Client) DeleteProjectApiKey(projectID string, apiKeyID string) error

DeleteProjectApiKey permanently removes an API key. Parameters:

  • projectID: The ID of the project the API key belongs to
  • apiKeyID: The ID of the API key to delete

Returns an error if the deletion fails or the key doesn't exist.

func (*Client) DeleteProjectServiceAccount

func (c *Client) DeleteProjectServiceAccount(projectID string, serviceAccountID string) error

DeleteProjectServiceAccount removes a service account from a project. This also invalidates any API keys associated with the service account.

Parameters:

  • projectID: The unique identifier of the project
  • serviceAccountID: The unique identifier of the service account to delete

Returns an error if the deletion fails or if the caller lacks permission. This operation cannot be undone, and any applications using the service account's API key will lose access immediately.

func (*Client) DeleteProjectUser

func (c *Client) DeleteProjectUser(projectID string, userID string) error

DeleteProjectUser removes a user from a project. This revokes all of the user's access to the project resources.

Parameters:

  • projectID: The unique identifier of the project
  • userID: The unique identifier of the user to remove

Returns an error if the deletion fails or if the caller lacks permission. The last owner of a project cannot be removed.

func (*Client) DeleteUser

func (c *Client) DeleteUser(id string) error

DeleteUser removes a user from the organization.

Parameters:

  • id: The unique identifier of the user to delete

Returns an error if deletion fails or nil on success.

func (*Client) GetAudioSpeechesUsage added in v0.3.1

func (c *Client) GetAudioSpeechesUsage(queryParams map[string]string) (*AudioSpeechesUsageResponse, error)

GetAudioSpeechesUsage retrieves usage statistics for text-to-speech API calls. The response includes character counts, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetAudioTranscriptionsUsage added in v0.3.1

func (c *Client) GetAudioTranscriptionsUsage(queryParams map[string]string) (*AudioTranscriptionsUsageResponse, error)

GetAudioTranscriptionsUsage retrieves usage statistics for speech-to-text API calls. The response includes audio duration, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetCertificate added in v0.6.0

func (c *Client) GetCertificate(certificateID string, includeContent bool) (*Certificate, error)

GetCertificate fetches details of a specific certificate. This can be used to get the current state of any certificate in the organization.

Parameters:

  • certificateID: The unique identifier of the certificate to retrieve
  • includeContent: Whether to include the PEM certificate content in the response

Returns the Certificate details or an error if retrieval fails. Returns an error if the certificate ID does not exist or if the caller lacks permission.

func (*Client) GetCodeInterpreterUsage added in v0.3.1

func (c *Client) GetCodeInterpreterUsage(queryParams map[string]string) (*CodeInterpreterUsageResponse, error)

GetCodeInterpreterUsage retrieves usage statistics for code interpreter sessions. The response includes session counts, duration, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project

Returns the usage statistics or an error if the request fails.

func (*Client) GetCompletionsUsage added in v0.3.1

func (c *Client) GetCompletionsUsage(queryParams map[string]string) (*CompletionsUsageResponse, error)

GetCompletionsUsage retrieves usage statistics for text completion API calls. The response includes token counts, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetCostsUsage added in v0.3.1

func (c *Client) GetCostsUsage(queryParams map[string]string) (*CostsUsageResponse, error)

GetCostsUsage retrieves billing cost statistics across all services. The response includes monetary amounts, line items, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project

Returns the cost statistics or an error if the request fails.

func (*Client) GetEmbeddingsUsage added in v0.3.1

func (c *Client) GetEmbeddingsUsage(queryParams map[string]string) (*EmbeddingsUsageResponse, error)

GetEmbeddingsUsage retrieves usage statistics for text embedding API calls. The response includes token counts, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetImagesUsage added in v0.3.1

func (c *Client) GetImagesUsage(queryParams map[string]string) (*ImagesUsageResponse, error)

GetImagesUsage retrieves usage statistics for image generation API calls. The response includes image counts, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetModerationsUsage added in v0.3.1

func (c *Client) GetModerationsUsage(queryParams map[string]string) (*ModerationsUsageResponse, error)

GetModerationsUsage retrieves usage statistics for content moderation API calls. The response includes token counts, request counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project
  • user_id: Filter by specific user
  • api_key_id: Filter by specific API key

Returns the usage statistics or an error if the request fails.

func (*Client) GetVectorStoresUsage added in v0.3.1

func (c *Client) GetVectorStoresUsage(queryParams map[string]string) (*VectorStoresUsageResponse, error)

GetVectorStoresUsage retrieves usage statistics for vector storage operations. The response includes storage size, vector counts, and other metrics aggregated by time buckets.

Parameters:

  • queryParams: Optional query parameters for filtering and pagination. Supported parameters include:
  • start_time: Start of the time range (Unix timestamp)
  • end_time: End of the time range (Unix timestamp)
  • limit: Maximum number of buckets to return
  • after: Pagination token for the next page
  • project_id: Filter by specific project

Returns the usage statistics or an error if the request fails.

func (*Client) ListAdminAPIKeys added in v0.3.0

func (c *Client) ListAdminAPIKeys(limit int, after string) (*ListResponse[AdminAPIKey], error)

ListAdminAPIKeys retrieves a paginated list of organization API keys.

Parameters:

  • limit: Maximum number of keys to return (0 for default)
  • after: Pagination token for fetching next page (empty string for first page)

Returns a ListResponse containing the API keys and pagination metadata. Returns an error if the API request fails.

func (*Client) ListAuditLogs

func (c *Client) ListAuditLogs(params *AuditLogListParams) (*ListResponse[AuditLog], error)

func (*Client) ListInvites

func (c *Client) ListInvites() ([]Invite, error)

ListInvites retrieves all invitations in the organization. It automatically handles pagination to fetch all available invites.

Returns a slice of all Invite objects or an error if the retrieval fails.

func (*Client) ListOrganizationCertificates added in v0.6.0

func (c *Client) ListOrganizationCertificates(limit int, after string, order string) (*ListResponse[Certificate], error)

ListOrganizationCertificates retrieves a paginated list of certificates in the organization. Certificates are used for mutual TLS authentication and can be managed at the organization level. Results are ordered by creation date, with newest certificates first.

Parameters:

  • limit: Maximum number of certificates to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)
  • order: Sort order for results ("asc" or "desc", defaults to "desc")

Returns a ListResponse containing the certificates and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListProjectApiKeys

func (c *Client) ListProjectApiKeys(projectID string, limit int, after string) (*ListResponse[ProjectApiKey], error)

ListProjectApiKeys lists all API keys associated with the specified project. Parameters:

  • projectID: The ID of the project to list API keys for
  • limit: Maximum number of keys to return (0 for API default)
  • after: Pagination cursor for fetching next page of results

Returns a ListResponse containing the API keys and pagination information.

func (*Client) ListProjectCertificates added in v0.6.0

func (c *Client) ListProjectCertificates(projectID string, limit int, after string, order string) (*ListResponse[Certificate], error)

ListProjectCertificates retrieves a paginated list of certificates available to a specific project. This includes both organization-level certificates and project-specific certificates. Results are ordered by creation date, with newest certificates first.

Parameters:

  • projectID: The unique identifier of the project
  • limit: Maximum number of certificates to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)
  • order: Sort order for results ("asc" or "desc", defaults to "desc")

Returns a ListResponse containing the certificates and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListProjectRateLimits added in v0.2.16

func (c *Client) ListProjectRateLimits(limit int, after string, projectId string) (*ListResponse[ProjectRateLimit], error)

ListProjectRateLimits retrieves a paginated list of rate limits for a specific project. Each rate limit configuration applies to a different model or API endpoint.

Parameters:

  • limit: Maximum number of rate limits to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)
  • projectId: The unique identifier of the project to list rate limits from

Returns a ListResponse containing the rate limits and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListProjectServiceAccounts

func (c *Client) ListProjectServiceAccounts(projectID string, limit int, after string) (*ListResponse[ProjectServiceAccount], error)

ListProjectServiceAccounts retrieves a paginated list of service accounts in a project. Service accounts are ordered by creation date, with newest accounts first.

Parameters:

  • projectID: The unique identifier of the project to list service accounts from
  • limit: Maximum number of accounts to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)

Returns a ListResponse containing the service accounts and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListProjectUsers

func (c *Client) ListProjectUsers(projectID string, limit int, after string) (*ListResponse[ProjectUser], error)

ListProjectUsers retrieves a paginated list of users in a specific project. Results are ordered by when users were added to the project, with most recent first.

Parameters:

  • projectID: The unique identifier of the project to list users from
  • limit: Maximum number of users to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)

Returns a ListResponse containing the project users and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListProjects

func (c *Client) ListProjects(limit int, after string, includeArchived bool) (*ListResponse[Project], error)

ListProjects retrieves a paginated list of projects in the organization. The results can be filtered to include or exclude archived projects. Results are ordered by creation date, with newest projects first.

Parameters:

  • limit: Maximum number of projects to return (0 for default, which is typically 20)
  • after: Pagination token for fetching next page (empty string for first page)
  • includeArchived: Whether to include archived projects in the response

Returns a ListResponse containing the projects and pagination metadata. The ListResponse includes the next pagination token if more results are available.

func (*Client) ListUsers

func (c *Client) ListUsers(limit int, after string) (*ListResponse[User], error)

ListUsers retrieves a paginated list of users in the organization.

Parameters:

  • limit: Maximum number of users to return (0 for default)
  • after: Pagination token for fetching next page (empty string for first page)

Returns a ListResponse containing the users and pagination metadata. Returns an error if the API request fails.

func (*Client) ModifyCertificate added in v0.6.0

func (c *Client) ModifyCertificate(certificateID string, name string) (*Certificate, error)

ModifyCertificate updates the properties of an existing certificate. Currently, only the certificate name can be modified. This operation cannot be performed on deleted certificates.

Parameters:

  • certificateID: The unique identifier of the certificate to modify
  • name: The new name for the certificate (must be unique within the organization)

Returns the updated Certificate object or an error if modification fails. Common errors include duplicate names or attempting to modify a deleted certificate.

func (*Client) ModifyProject

func (c *Client) ModifyProject(id string, name string) (*Project, error)

ModifyProject updates the properties of an existing project. Currently, only the project name can be modified. This operation cannot be performed on archived projects.

Parameters:

  • id: The unique identifier of the project to modify
  • name: The new name for the project (must be unique within the organization)

Returns the updated Project object or an error if modification fails. Common errors include duplicate names or attempting to modify an archived project.

func (*Client) ModifyProjectRateLimit added in v0.2.16

func (c *Client) ModifyProjectRateLimit(projectId, rateLimitId string, fields ProjectRateLimitRequestFields) (*ProjectRateLimit, error)

ModifyProjectRateLimit updates the rate limit configuration for a specific model within a project. Only the non-zero fields in the request will be updated.

Parameters:

  • projectId: The unique identifier of the project containing the rate limit
  • rateLimitId: The unique identifier of the rate limit configuration to modify
  • fields: The new values to set for the rate limit fields

Returns the updated ProjectRateLimit object or an error if modification fails. Common errors include invalid rate limit values or insufficient permissions.

func (*Client) ModifyProjectUser

func (c *Client) ModifyProjectUser(projectID string, userID string, role string) (*ProjectUser, error)

ModifyProjectUser updates a user's role within a project. This can be used to promote or demote a user's access level.

Parameters:

  • projectID: The unique identifier of the project
  • userID: The unique identifier of the user to modify
  • role: The new role to assign to the user (must be a valid RoleType)

Returns the updated ProjectUser object or an error if modification fails. Common errors include invalid roles or insufficient permissions.

func (*Client) ModifyUserRole

func (c *Client) ModifyUserRole(id string, role string) error

ModifyUserRole updates a user's role within the organization.

Parameters:

  • id: The unique identifier of the user to modify
  • role: The new role to assign to the user

Returns an error if the role modification fails or nil on success.

func (*Client) RetrieveAdminAPIKey added in v0.3.0

func (c *Client) RetrieveAdminAPIKey(apiKeyID string) (*AdminAPIKey, error)

RetrieveAdminAPIKey fetches details of a specific organization API key.

Parameters:

  • apiKeyID: The unique identifier of the API key to retrieve

Returns the AdminAPIKey details or an error if retrieval fails.

func (*Client) RetrieveInvite

func (c *Client) RetrieveInvite(id string) (*Invite, error)

RetrieveInvite fetches details of a specific invitation.

Parameters:

  • id: The unique identifier of the invitation to retrieve

Returns the Invite details or an error if retrieval fails.

func (*Client) RetrieveProject

func (c *Client) RetrieveProject(id string) (*Project, error)

RetrieveProject fetches details of a specific project. This can be used to get the current state of any project, including archived ones.

Parameters:

  • id: The unique identifier of the project to retrieve

Returns the Project details or an error if retrieval fails. Returns an error if the project ID does not exist or if the caller lacks permission.

func (*Client) RetrieveProjectApiKey

func (c *Client) RetrieveProjectApiKey(projectID string, apiKeyID string) (*ProjectApiKey, error)

RetrieveProjectApiKey gets a specific API key by its ID. Parameters:

  • projectID: The ID of the project the API key belongs to
  • apiKeyID: The ID of the specific API key to retrieve

Returns the ProjectApiKey if found, or an error if not found or on API failure.

func (*Client) RetrieveProjectServiceAccount

func (c *Client) RetrieveProjectServiceAccount(projectID string, serviceAccountID string) (*ProjectServiceAccount, error)

RetrieveProjectServiceAccount fetches details about a specific service account. The API key value is never included in the response, even if one exists.

Parameters:

  • projectID: The unique identifier of the project
  • serviceAccountID: The unique identifier of the service account to retrieve

Returns the ProjectServiceAccount details or an error if retrieval fails. Returns an error if the service account does not exist or if the caller lacks permission.

func (*Client) RetrieveProjectUser

func (c *Client) RetrieveProjectUser(projectID string, userID string) (*ProjectUser, error)

RetrieveProjectUser fetches details about a specific user's membership in a project.

Parameters:

  • projectID: The unique identifier of the project
  • userID: The unique identifier of the user to retrieve

Returns the ProjectUser details or an error if retrieval fails. Returns an error if the user is not a member of the project or if the caller lacks permission.

func (*Client) RetrieveUser

func (c *Client) RetrieveUser(id string) (*User, error)

RetrieveUser fetches details of a specific user in the organization.

Parameters:

  • id: The unique identifier of the user to retrieve

Returns the User details or an error if retrieval fails.

func (*Client) UploadCertificate added in v0.6.0

func (c *Client) UploadCertificate(content string, name string) (*Certificate, error)

UploadCertificate uploads a new certificate to the organization. The certificate content must be provided in PEM format. New certificates are created in an inactive state and must be explicitly activated.

Parameters:

  • content: The PEM-encoded certificate content
  • name: The human-readable name for the certificate (must be unique)

Returns the created Certificate object or an error if upload fails. Common errors include invalid certificate format or duplicate names.

type CodeInterpreterUsage added in v0.3.1

type CodeInterpreterUsage struct {
	// SessionDuration is the duration of the session in seconds.
	SessionDuration int `json:"session_duration"`

	// Model identifies which code interpreter model was used.
	Model string `json:"model"`
}

CodeInterpreterUsage represents the usage details for a code interpreter session. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeCodeInterpreter.

type CodeInterpreterUsageBucket added in v0.3.1

type CodeInterpreterUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed code interpreter usage data.
	Results []CodeInterpreterUsageResult `json:"results"`
}

CodeInterpreterUsageBucket represents a time-based bucket of code interpreter usage data. Each bucket contains aggregated statistics about code interpreter sessions.

type CodeInterpreterUsageResponse added in v0.3.1

type CodeInterpreterUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of code interpreter usage buckets.
	Data []CodeInterpreterUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

CodeInterpreterUsageResponse represents the response from the code interpreter usage endpoint. This provides detailed statistics about code interpreter session usage.

type CodeInterpreterUsageResult added in v0.3.1

type CodeInterpreterUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// NumSessions is the number of code interpreter sessions used.
	NumSessions int `json:"num_sessions"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`
}

CodeInterpreterUsageResult represents a single code interpreter usage record. This provides detailed information about code interpreter session counts and resource utilization.

type CompletionsUsage added in v0.3.1

type CompletionsUsage struct {
	// PromptTokens is the number of tokens in the input prompt.
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens in the generated completion.
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the sum of prompt and completion tokens.
	TotalTokens int `json:"total_tokens"`

	// Model identifies which completion model was used.
	Model string `json:"model"`
}

CompletionsUsage represents the usage details for a completions request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeCompletions.

type CompletionsUsageBucket added in v0.3.1

type CompletionsUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed completions usage data.
	Results []CompletionsUsageResult `json:"results"`
}

CompletionsUsageBucket represents a time-based bucket of completions usage data. Each bucket contains aggregated statistics about completion API usage.

type CompletionsUsageResponse added in v0.3.1

type CompletionsUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of completions usage buckets.
	Data []CompletionsUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

CompletionsUsageResponse represents the response from the completions usage endpoint. This provides detailed statistics about text completion API usage.

type CompletionsUsageResult added in v0.3.1

type CompletionsUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// InputTokens is the number of tokens in the prompt.
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the number of tokens in the completion.
	OutputTokens int `json:"output_tokens"`

	// InputCachedTokens is the number of tokens served from cache.
	InputCachedTokens int `json:"input_cached_tokens"`

	// InputAudioTokens is the number of tokens from audio input.
	InputAudioTokens int `json:"input_audio_tokens"`

	// OutputAudioTokens is the number of tokens in audio output.
	OutputAudioTokens int `json:"output_audio_tokens"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which model was used.
	Model string `json:"model"`

	// Batch contains information about batch processing, if applicable.
	Batch any `json:"batch"`
}

CompletionsUsageResult represents a single completions usage record. This provides detailed information about token usage and request counts.

type CostAmount added in v0.3.1

type CostAmount struct {
	// Value is the numeric amount.
	Value float64 `json:"value"`

	// Currency is the three-letter currency code (e.g., "USD").
	Currency string `json:"currency"`
}

CostAmount represents a monetary amount with its currency.

type CostsUsage added in v0.3.1

type CostsUsage struct {
	// Amount is the monetary value of the cost.
	Amount float64 `json:"amount"`

	// Currency is the three-letter currency code (e.g., "USD").
	Currency string `json:"currency"`

	// Period is the billing period this cost applies to.
	Period string `json:"period"`
}

CostsUsage represents the usage details for billing costs. This is used in the UsageDetails field of UsageRecord when Type is related to costs.

type CostsUsageBucket added in v0.3.1

type CostsUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed costs usage data.
	Results []CostsUsageResult `json:"results"`
}

CostsUsageBucket represents a time-based bucket of costs usage data. Each bucket contains aggregated billing information for all services.

type CostsUsageResponse added in v0.3.1

type CostsUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of costs usage buckets.
	Data []CostsUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

CostsUsageResponse represents the response from the costs usage endpoint. This provides detailed statistics about billing and costs across all services.

type CostsUsageResult added in v0.3.1

type CostsUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Amount contains the cost value and currency information.
	Amount CostAmount `json:"amount"`

	// LineItem contains additional details about what the cost is for.
	// The structure varies depending on the service type.
	LineItem any `json:"line_item"`

	// ProjectID identifies which project generated this cost.
	ProjectID string `json:"project_id"`
}

CostsUsageResult represents a single costs usage record. This provides detailed information about billing amounts and associated line items.

type EffectiveAt added in v0.2.14

type EffectiveAt struct {
	Gte int64 `json:"gte,omitempty"`
	Gt  int64 `json:"gt,omitempty"`
	Lte int64 `json:"lte,omitempty"`
	Lt  int64 `json:"lt,omitempty"`
}

type EmbeddingsUsage added in v0.3.1

type EmbeddingsUsage struct {
	// PromptTokens is the number of tokens processed for embedding.
	PromptTokens int `json:"prompt_tokens"`

	// Model identifies which embedding model was used.
	Model string `json:"model"`
}

EmbeddingsUsage represents the usage details for an embeddings request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeEmbeddings.

type EmbeddingsUsageBucket added in v0.3.1

type EmbeddingsUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed embeddings usage data.
	Results []EmbeddingsUsageResult `json:"results"`
}

EmbeddingsUsageBucket represents a time-based bucket of embeddings usage data. Each bucket contains aggregated statistics about embedding API usage.

type EmbeddingsUsageResponse added in v0.3.1

type EmbeddingsUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of embeddings usage buckets.
	Data []EmbeddingsUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

EmbeddingsUsageResponse represents the response from the embeddings usage endpoint. This provides detailed statistics about text embedding API usage.

type EmbeddingsUsageResult added in v0.3.1

type EmbeddingsUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// InputTokens is the number of tokens processed for embedding.
	InputTokens int `json:"input_tokens"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which embedding model was used.
	Model string `json:"model"`
}

EmbeddingsUsageResult represents a single embeddings usage record. This provides detailed information about token usage and request counts for text embedding operations.

type IPAddressDetails added in v0.6.0

type IPAddressDetails struct {
	Country    string `json:"country,omitempty"`
	City       string `json:"city,omitempty"`
	Region     string `json:"region,omitempty"`
	RegionCode string `json:"region_code,omitempty"`
	ASN        string `json:"asn,omitempty"`
	Latitude   string `json:"latitude,omitempty"`
	Longitude  string `json:"longitude,omitempty"`
}

IPAddressDetails contains geolocation information for an IP address

type ImagesUsage added in v0.3.1

type ImagesUsage struct {
	// Images is the number of images generated.
	Images int `json:"images"`

	// Size specifies the resolution of generated images.
	// Common values are "256x256", "512x512", "1024x1024".
	Size string `json:"size"`

	// Model identifies which image generation model was used.
	Model string `json:"model"`
}

ImagesUsage represents the usage details for an image generation request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeImages.

type ImagesUsageBucket added in v0.3.1

type ImagesUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed images usage data.
	Results []ImagesUsageResult `json:"results"`
}

ImagesUsageBucket represents a time-based bucket of images usage data. Each bucket contains aggregated statistics about image generation API usage.

type ImagesUsageResponse added in v0.3.1

type ImagesUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of images usage buckets.
	Data []ImagesUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

ImagesUsageResponse represents the response from the images usage endpoint. This provides detailed statistics about image generation API usage.

type ImagesUsageResult added in v0.3.1

type ImagesUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Images is the number of images generated.
	Images int `json:"images"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// Size specifies the resolution of generated images.
	// Common values are "256x256", "512x512", "1024x1024".
	Size string `json:"size"`

	// Source indicates the image generation method.
	// Can be "generation" for new images or "edit" for modifications.
	Source string `json:"source"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which image generation model was used.
	Model string `json:"model"`
}

ImagesUsageResult represents a single images usage record. This provides detailed information about image generation counts and configuration options used.

type Invite

type Invite struct {
	// ObjectType identifies the type of this resource.
	ObjectType string `json:"object"`
	// ID is the unique identifier for this invitation.
	ID string `json:"id"`
	// Email is the address of the invited user.
	Email string `json:"email"`
	// Role specifies the permissions the user will have upon accepting.
	Role string `json:"role"`
	// Status indicates the current state of the invitation (e.g., pending, accepted).
	Status string `json:"status"`
	// CreatedAt is the timestamp when this invitation was created.
	CreatedAt UnixSeconds `json:"created_at"`
	// ExpiresAt is the timestamp when this invitation will expire if not accepted.
	ExpiresAt UnixSeconds `json:"expires_at"`
	// AcceptedAt is the timestamp when the invitation was accepted, if applicable.
	AcceptedAt *UnixSeconds `json:"accepted_at,omitempty"`
}

Invite represents an invitation for a user to join an OpenAI organization. Invites have a limited lifetime and can be in various states (pending, accepted, expired).

func (*Invite) String added in v0.3.1

func (i *Invite) String() string

String returns a human-readable string representation of the Invite. It includes the invitation's ID, email, role, status, and acceptance time if applicable.

type InviteAccepted added in v0.2.11

type InviteAccepted struct {
	ID string `json:"id"`
}

type InviteDeleted added in v0.2.11

type InviteDeleted struct {
	ID string `json:"id"`
}

type InviteSent

type InviteSent struct {
	ID   string `json:"id"`
	Data struct {
		Email string `json:"email"`
	} `json:"data"`
}

type ListResponse

type ListResponse[T any] struct {
	// Object identifies the type of the response, typically "list".
	Object string `json:"object"`
	// Data contains the actual list of items of type T.
	Data []T `json:"data"`
	// FirstID is the ID of the first item in this page.
	FirstID string `json:"first_id"`
	// LastID is the ID of the last item in this page.
	LastID string `json:"last_id"`
	// HasMore indicates whether there are more items available in subsequent pages.
	HasMore bool `json:"has_more"`
}

ListResponse is a generic container for paginated API responses. It provides metadata about the list (such as pagination tokens) and the actual data items.

func Get

func Get[T any](client *resty.Client, endpoint string, queryParams map[string]string) (*ListResponse[T], error)

Get makes a GET request to retrieve a list of resources of type T. It supports query parameters and handles pagination through the ListResponse type. Returns a pointer to the ListResponse containing the resources and any error encountered.

func (*ListResponse[T]) String added in v0.3.1

func (lr *ListResponse[T]) String() string

String returns a pretty-printed string representation of the ListResponse. It includes all metadata and a formatted list of all items in the Data field.

type LoginFailed added in v0.2.11

type LoginFailed struct {
	ErrorCode    string `json:"error_code"`
	ErrorMessage string `json:"error_message"`
}

type LoginSucceeded

type LoginSucceeded struct {
	Object      string `json:"object"`
	ID          string `json:"id"`
	Type        string `json:"type"`
	EffectiveAt int64  `json:"effective_at"`
	Actor       Actor  `json:"actor"`
}

type LogoutFailed added in v0.2.11

type LogoutFailed struct {
	ErrorCode    string `json:"error_code"`
	ErrorMessage string `json:"error_message"`
}

type ModerationsUsage added in v0.3.1

type ModerationsUsage struct {
	// PromptTokens is the number of tokens processed for moderation.
	PromptTokens int `json:"prompt_tokens"`

	// Model identifies which moderation model was used.
	Model string `json:"model"`
}

ModerationsUsage represents the usage details for a moderations request. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeModerations.

type ModerationsUsageBucket added in v0.3.1

type ModerationsUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed moderations usage data.
	Results []ModerationsUsageResult `json:"results"`
}

ModerationsUsageBucket represents a time-based bucket of moderations usage data. Each bucket contains aggregated statistics about content moderation API usage.

type ModerationsUsageResponse added in v0.3.1

type ModerationsUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of moderations usage buckets.
	Data []ModerationsUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

ModerationsUsageResponse represents the response from the moderations usage endpoint. This provides detailed statistics about content moderation API usage.

type ModerationsUsageResult added in v0.3.1

type ModerationsUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// InputTokens is the number of tokens processed for moderation.
	InputTokens int `json:"input_tokens"`

	// NumModelRequests is the number of API calls made.
	NumModelRequests int `json:"num_model_requests"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage.
	UserID string `json:"user_id"`

	// APIKeyID identifies which API key was used.
	APIKeyID string `json:"api_key_id"`

	// Model identifies which moderation model was used.
	Model string `json:"model"`
}

ModerationsUsageResult represents a single moderations usage record. This provides detailed information about token usage and request counts for content moderation operations.

type OpenAIOrgsClient added in v0.3.1

type OpenAIOrgsClient interface {
	// Project Management
	ListProjects(limit int, after string, includeArchived bool) (*ListResponse[Project], error)
	CreateProject(name string) (*Project, error)
	RetrieveProject(id string) (*Project, error)
	ModifyProject(id string, name string) (*Project, error)
	ArchiveProject(id string) (*Project, error)

	// Project Users
	ListProjectUsers(projectID string, limit int, after string) (*ListResponse[ProjectUser], error)
	CreateProjectUser(projectID string, userID string, role string) (*ProjectUser, error)
	RetrieveProjectUser(projectID string, userID string) (*ProjectUser, error)
	ModifyProjectUser(projectID string, userID string, role string) (*ProjectUser, error)
	DeleteProjectUser(projectID string, userID string) error

	// Organization Users
	ListUsers(limit int, after string) (*ListResponse[User], error)
	RetrieveUser(id string) (*User, error)
	DeleteUser(id string) error
	ModifyUserRole(id string, role string) error

	// Organization Invites
	ListInvites(limit int, after string) (*ListResponse[Invite], error)
	CreateInvite(email string, role string) (*Invite, error)
	RetrieveInvite(id string) (*Invite, error)
	DeleteInvite(id string) error

	// Project API Keys
	ListProjectApiKeys(projectID string, limit int, after string) (*ListResponse[ProjectApiKey], error)
	RetrieveProjectApiKey(projectID string, apiKeyID string) (*ProjectApiKey, error)
	DeleteProjectApiKey(projectID string, apiKeyID string) error

	// Admin API Keys
	ListAdminAPIKeys(limit int, after string) (*ListResponse[AdminAPIKey], error)
	CreateAdminAPIKey(name string, scopes []string) (*AdminAPIKey, error)
	RetrieveAdminAPIKey(apiKeyID string) (*AdminAPIKey, error)
	DeleteAdminAPIKey(apiKeyID string) error

	// Project Service Accounts
	ListProjectServiceAccounts(projectID string, limit int, after string) (*ListResponse[ProjectServiceAccount], error)
	CreateProjectServiceAccount(projectID string, name string) (*ProjectServiceAccount, error)
	RetrieveProjectServiceAccount(projectID string, serviceAccountID string) (*ProjectServiceAccount, error)
	DeleteProjectServiceAccount(projectID string, serviceAccountID string) error

	// Project Rate Limits
	ListProjectRateLimits(limit int, after string, projectId string) (*ListResponse[ProjectRateLimit], error)

	// Audit Logs
	ListAuditLogs(params *AuditLogListParams) (*ListResponse[AuditLog], error)

	// Organization Certificates
	ListOrganizationCertificates(limit int, after string, order string) (*ListResponse[Certificate], error)
	UploadCertificate(content string, name string) (*Certificate, error)
	GetCertificate(certificateID string, includeContent bool) (*Certificate, error)
	ModifyCertificate(certificateID string, name string) (*Certificate, error)
	DeleteCertificate(certificateID string) (*CertificateDeletedResponse, error)
	ActivateOrganizationCertificates(certificateIDs []string) (*CertificateActivationResponse, error)
	DeactivateOrganizationCertificates(certificateIDs []string) (*CertificateActivationResponse, error)

	// Project Certificates
	ListProjectCertificates(projectID string, limit int, after string, order string) (*ListResponse[Certificate], error)
	ActivateProjectCertificates(projectID string, certificateIDs []string) (*CertificateActivationResponse, error)
	DeactivateProjectCertificates(projectID string, certificateIDs []string) (*CertificateActivationResponse, error)
}

OpenAIOrgsClient defines the interface for interacting with the OpenAI Organizations API.

type OrganizationUpdated

type OrganizationUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		Name string `json:"name,omitempty"`
	} `json:"changes_requested"`
}

type Owner

type Owner struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`
	// ID is the unique identifier for this owner.
	ID string `json:"id"`
	// Name is the display name of the owner.
	Name string `json:"name"`
	// Type indicates whether this is a user or service account owner.
	Type OwnerType `json:"type"`
	// User contains user-specific details if Type is OwnerTypeUser.
	User *User `json:"user,omitempty"`
	// SA contains service account details if Type is OwnerTypeServiceAccount.
	SA *ProjectServiceAccount `json:"service_account,omitempty"`
}

Owner represents an entity that can own or be assigned to resources. An owner can be either a user or a service account, as indicated by the Type field.

func (*Owner) String added in v0.3.1

func (o *Owner) String() string

String returns a human-readable string representation of the Owner. It includes basic metadata and owner-specific information based on the owner type.

type OwnerType

type OwnerType string

OwnerType represents the type of an owner entity. It distinguishes between user accounts and service accounts.

const (
	// OwnerTypeUser indicates the owner is a human user account.
	OwnerTypeUser OwnerType = "user"
	// OwnerTypeServiceAccount indicates the owner is a service account.
	OwnerTypeServiceAccount OwnerType = "service_account"
)

type Project

type Project struct {
	// Object identifies the type of this resource.
	// This will always be "project" for Project objects.
	Object string `json:"object"`

	// ID is the unique identifier for this project.
	// This is assigned by OpenAI and cannot be changed.
	ID string `json:"id"`

	// Name is the human-readable identifier for the project.
	// This can be updated using ModifyProject.
	Name string `json:"name"`

	// CreatedAt is the timestamp when this project was created.
	// The timestamp is in Unix epoch seconds.
	CreatedAt UnixSeconds `json:"created_at"`

	// ArchivedAt is the timestamp when this project was archived, if applicable.
	// The timestamp is in Unix epoch seconds. Will be nil for active projects.
	ArchivedAt *UnixSeconds `json:"archived_at,omitempty"`

	// Status indicates the current state of the project.
	// Possible values are "active" or "archived".
	Status string `json:"status"`
}

Project represents a project within an OpenAI organization. Projects are containers for resources, members, billing limits and settings that can be managed independently. Each project has its own API keys, rate limits, and user permissions, allowing for isolated management of different workloads or teams within the same organization.

func (*Project) String added in v0.3.1

func (p *Project) String() string

String returns a human-readable string representation of the Project. It includes the project's ID, name, and current status (including archived state). This is useful for logging and debugging purposes.

type ProjectApiKey

type ProjectApiKey struct {
	// Object is the type identifier of this resource.
	Object string `json:"object"`
	// RedactedValue is the partially hidden API key string.
	RedactedValue string `json:"redacted_value"`
	// Name is the user-assigned identifier.
	Name string `json:"name"`
	// CreatedAt records when this API key was created.
	CreatedAt UnixSeconds `json:"created_at"`
	// ID uniquely identifies this API key.
	ID string `json:"id"`
	// Owner identifies the entity that controls this API key.
	Owner Owner `json:"owner"`
}

ProjectApiKey represents an API key for project authentication.

func (*ProjectApiKey) String added in v0.3.1

func (pak *ProjectApiKey) String() string

String implements the Stringer interface, returning a concise representation of the API key.

type ProjectArchived added in v0.2.11

type ProjectArchived struct {
	ID string `json:"id"`
}

ProjectArchived represents the details for project.archived events

type ProjectCreated added in v0.2.11

type ProjectCreated struct {
	ID   string `json:"id"`
	Data struct {
		Name  string `json:"name"`
		Title string `json:"title"`
	} `json:"data"`
}

ProjectCreated represents the details for project.created events

type ProjectRateLimit added in v0.2.16

type ProjectRateLimit struct {
	// Object identifies the type of this resource.
	// This will always be "project_rate_limit" for ProjectRateLimit objects.
	Object string `json:"object"`

	// ID is the unique identifier for this rate limit configuration.
	ID string `json:"id"`

	// Model specifies which OpenAI model this rate limit applies to.
	// Examples include "gpt-4", "gpt-3.5-turbo", "dall-e-3", etc.
	Model string `json:"model"`

	// MaxRequestsPer1Minute defines the maximum number of API requests
	// allowed within a 1-minute rolling window.
	MaxRequestsPer1Minute int64 `json:"max_requests_per_1_minute"`

	// MaxTokensPer1Minute defines the maximum number of tokens (input + output)
	// that can be processed within a 1-minute rolling window.
	MaxTokensPer1Minute int64 `json:"max_tokens_per_1_minute"`

	// MaxImagesPer1Minute defines the maximum number of images that can be
	// generated within a 1-minute rolling window.
	MaxImagesPer1Minute int64 `json:"max_images_per_1_minute"`

	// MaxAudioMegabytesPer1Minute defines the maximum audio data size in MB
	// that can be processed within a 1-minute rolling window.
	MaxAudioMegabytesPer1Minute int64 `json:"max_audio_megabytes_per_1_minute"`

	// MaxRequestsPer1Day defines the maximum number of API requests
	// allowed within a 24-hour rolling window.
	MaxRequestsPer1Day int64 `json:"max_requests_per_1_day"`

	// Batch1DayMaxInputTokens defines the maximum number of input tokens
	// allowed for batch processing within a 24-hour rolling window.
	Batch1DayMaxInputTokens int64 `json:"batch_1_day_max_input_tokens"`
}

ProjectRateLimit represents the rate limiting configuration for a specific model within a project. Rate limits control the maximum usage of OpenAI's APIs across different time windows and resource types (requests, tokens, images, audio).

func (*ProjectRateLimit) String added in v0.3.1

func (prl *ProjectRateLimit) String() string

String returns a human-readable string representation of the ProjectRateLimit. This is useful for logging and debugging purposes, showing key rate limit values.

type ProjectRateLimitRequestFields added in v0.2.16

type ProjectRateLimitRequestFields struct {
	// MaxRequestsPer1Minute defines the new maximum requests per minute.
	// Set to 0 to leave unchanged.
	MaxRequestsPer1Minute int64

	// MaxTokensPer1Minute defines the new maximum tokens per minute.
	// Set to 0 to leave unchanged.
	MaxTokensPer1Minute int64

	// MaxImagesPer1Minute defines the new maximum images per minute.
	// Set to 0 to leave unchanged.
	MaxImagesPer1Minute int64

	// MaxAudioMegabytesPer1Minute defines the new maximum audio MB per minute.
	// Set to 0 to leave unchanged.
	MaxAudioMegabytesPer1Minute int64

	// MaxRequestsPer1Day defines the new maximum requests per day.
	// Set to 0 to leave unchanged.
	MaxRequestsPer1Day int64

	// Batch1DayMaxInputTokens defines the new maximum batch input tokens per day.
	// Set to 0 to leave unchanged.
	Batch1DayMaxInputTokens int64
}

ProjectRateLimitRequestFields defines the modifiable fields when updating a rate limit. All fields are optional - only non-zero values will be included in the update request. This allows for partial updates of rate limit configurations.

type ProjectServiceAccount

type ProjectServiceAccount struct {
	// Object identifies the type of this resource.
	// This will always be "project_service_account" for ProjectServiceAccount objects.
	Object string `json:"object"`

	// ID is the unique identifier for this service account.
	ID string `json:"id"`

	// Name is the human-readable identifier for the service account.
	// This should be descriptive of the account's purpose.
	Name string `json:"name"`

	// Role defines the service account's access level within the project.
	// Valid values are defined by RoleType: "admin", "developer", "viewer".
	Role string `json:"role"`

	// CreatedAt is the timestamp when this service account was created.
	// The timestamp is in Unix epoch seconds.
	CreatedAt UnixSeconds `json:"created_at"`

	// APIKey contains the API key details if one was generated during creation.
	// This field is only populated in the response of CreateProjectServiceAccount.
	// Subsequent retrievals will not include the API key value.
	APIKey *ProjectServiceAccountAPIKey `json:"api_key,omitempty"`
}

ProjectServiceAccount represents a service account within a project. Service accounts are non-human identities that can be used for automated access to project resources. Each service account can have its own API key and role.

func (*ProjectServiceAccount) String added in v0.3.1

func (psa *ProjectServiceAccount) String() string

String returns a human-readable string representation of the ProjectServiceAccount. This is useful for logging and debugging purposes. The API key value is never included in the string representation for security reasons.

type ProjectServiceAccountAPIKey added in v0.2.6

type ProjectServiceAccountAPIKey struct {
	// Object identifies the type of this resource.
	// This will always be "project_service_account_api_key" for ProjectServiceAccountAPIKey objects.
	Object string `json:"object"`

	// Value is the actual API key string to be used for authentication.
	// This value is only returned once during creation and cannot be retrieved later.
	Value string `json:"value"`

	// Name is an optional descriptive name for the API key.
	// This can help identify the key's purpose or usage context.
	Name *string `json:"name"`

	// CreatedAt is the timestamp when this API key was created.
	// The timestamp is in Unix epoch seconds.
	CreatedAt UnixSeconds `json:"created_at"`

	// ID is the unique identifier for this API key.
	// This can be used to identify and revoke the key later.
	ID string `json:"id"`
}

ProjectServiceAccountAPIKey represents an API key associated with a service account. The API key value is only returned once during creation and cannot be retrieved later.

type ProjectUpdated added in v0.2.11

type ProjectUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		Title string `json:"title"`
	} `json:"changes_requested"`
}

ProjectUpdated represents the details for project.updated events

type ProjectUser

type ProjectUser struct {
	// Object identifies the type of this resource.
	// This will always be "project_user" for ProjectUser objects.
	Object string `json:"object"`

	// ID is the unique identifier of the user.
	// This matches the user's organization-level ID.
	ID string `json:"id"`

	// Name is the user's full name.
	// This is for display purposes and matches their organization profile.
	Name string `json:"name"`

	// Email is the user's email address.
	// This is the primary identifier for the user in the UI.
	Email string `json:"email"`

	// Role defines the user's access level within the project.
	// Valid values are defined by RoleType: "owner", "admin", "developer", "viewer".
	Role string `json:"role"`

	// AddedAt is the timestamp when the user was added to the project.
	// The timestamp is in Unix epoch seconds.
	AddedAt UnixSeconds `json:"added_at"`
}

ProjectUser represents a user's membership and role within a specific project. Each ProjectUser entry defines the access level and permissions a user has within the project context. Users can have different roles across different projects within the same organization.

func (*ProjectUser) String added in v0.3.1

func (pu *ProjectUser) String() string

String returns a human-readable string representation of the ProjectUser. This is useful for logging and debugging purposes.

type RateLimitDeleted added in v0.2.11

type RateLimitDeleted struct {
	ID string `json:"id"`
}

RateLimitDeleted represents the details for rate_limit.deleted events

type RateLimitUpdated added in v0.2.11

type RateLimitUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		MaxRequestsPer1Minute       int `json:"max_requests_per_1_minute,omitempty"`
		MaxTokensPer1Minute         int `json:"max_tokens_per_1_minute,omitempty"`
		MaxImagesPer1Minute         int `json:"max_images_per_1_minute,omitempty"`
		MaxAudioMegabytesPer1Minute int `json:"max_audio_megabytes_per_1_minute,omitempty"`
		MaxRequestsPer1Day          int `json:"max_requests_per_1_day,omitempty"`
		Batch1DayMaxInputTokens     int `json:"batch_1_day_max_input_tokens,omitempty"`
	} `json:"changes_requested"`
}

RateLimitUpdated represents the details for rate_limit.updated events

type RoleType

type RoleType string

RoleType represents the level of access and permissions an entity has.

const (
	// RoleTypeOwner grants full administrative access.
	RoleTypeOwner RoleType = "owner"
	// RoleTypeMember grants standard member access.
	RoleTypeMember RoleType = "member"
)

func ParseRoleType

func ParseRoleType(s string) RoleType

ParseRoleType converts a string to a RoleType. Returns an empty RoleType if the string doesn't match a known role.

type ServiceAccountCreated added in v0.2.11

type ServiceAccountCreated struct {
	ID   string `json:"id"`
	Data struct {
		Role string `json:"role"` // Either "owner" or "member"
	} `json:"data"`
}

ServiceAccountCreated represents the details for service_account.created events

type ServiceAccountDeleted added in v0.2.11

type ServiceAccountDeleted struct {
	ID string `json:"id"`
}

ServiceAccountDeleted represents the details for service_account.deleted events

type ServiceAccountUpdated added in v0.2.11

type ServiceAccountUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		Role string `json:"role"` // Either "owner" or "member"
	} `json:"changes_requested"`
}

ServiceAccountUpdated represents the details for service_account.updated events

type Session added in v0.2.11

type Session struct {
	User             AuditUser         `json:"user"`
	IPAddress        string            `json:"ip_address"`
	UserAgent        string            `json:"user_agent"`
	JA3              string            `json:"ja3,omitempty"`
	JA4              string            `json:"ja4,omitempty"`
	IPAddressDetails *IPAddressDetails `json:"ip_address_details,omitempty"`
}

Session represents user session information

type UnixSeconds

type UnixSeconds time.Time

UnixSeconds represents a Unix timestamp as a time.Time

func (UnixSeconds) MarshalJSON

func (us UnixSeconds) MarshalJSON() ([]byte, error)

func (UnixSeconds) String

func (ct UnixSeconds) String() string

func (UnixSeconds) Time

func (ct UnixSeconds) Time() time.Time

func (*UnixSeconds) UnmarshalJSON

func (us *UnixSeconds) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler interface

type UsageBucket added in v0.3.1

type UsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the raw usage data for this time bucket.
	// The actual structure depends on the usage type.
	Results json.RawMessage `json:"results"`
}

UsageBucket represents a time-based bucket of usage data. Each bucket contains usage statistics for a specific time window.

type UsageRecord added in v0.3.1

type UsageRecord struct {
	// ID uniquely identifies this usage record.
	ID string `json:"id"`

	// Object identifies the type of this resource.
	// This will always be "usage_record" for UsageRecord objects.
	Object string `json:"object"`

	// Timestamp indicates when this usage occurred.
	Timestamp time.Time `json:"timestamp"`

	// Type indicates what kind of usage this record represents.
	// This determines how to interpret the UsageDetails field.
	Type UsageType `json:"type"`

	// UsageDetails contains type-specific usage information.
	// The actual structure depends on the Type field.
	UsageDetails any `json:"usage_details"`

	// Cost is the monetary cost associated with this usage.
	Cost float64 `json:"cost"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`

	// UserID identifies which user generated this usage, if applicable.
	UserID string `json:"user_id,omitempty"`
}

UsageRecord represents a single usage record in the legacy format. This contains basic information about the usage and a type-specific details field.

func (*UsageRecord) String added in v0.3.1

func (ur *UsageRecord) String() string

String returns a human-readable string representation of the UsageRecord. This is useful for logging and debugging purposes. The format varies based on the Type field and corresponding UsageDetails structure.

type UsageResponse added in v0.3.1

type UsageResponse struct {
	// Object identifies the type of this resource.
	// This will always be "list" for UsageResponse objects.
	Object string `json:"object"`

	// Data contains the list of usage records.
	Data []UsageRecord `json:"data"`

	// FirstID is the ID of the first record in this page.
	FirstID string `json:"first_id"`

	// LastID is the ID of the last record in this page.
	LastID string `json:"last_id"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`
}

UsageResponse represents the response from the legacy usage endpoints. This format is being replaced by the more detailed type-specific responses.

type UsageType added in v0.3.1

type UsageType string

UsageType represents the type of usage (completions, embeddings, etc.). This is used to categorize usage records and determine how to parse their details.

const (
	// UsageTypeCompletions represents text completion API usage
	UsageTypeCompletions UsageType = "completions"
	// UsageTypeEmbeddings represents text embedding API usage
	UsageTypeEmbeddings UsageType = "embeddings"
	// UsageTypeModerations represents content moderation API usage
	UsageTypeModerations UsageType = "moderations"
	// UsageTypeImages represents image generation API usage
	UsageTypeImages UsageType = "images"
	// UsageTypeAudioSpeeches represents text-to-speech API usage
	UsageTypeAudioSpeeches UsageType = "audio_speeches"
	// UsageTypeAudioTranscriptions represents speech-to-text API usage
	UsageTypeAudioTranscriptions UsageType = "audio_transcriptions"
	// UsageTypeVectorStores represents vector storage operations usage
	UsageTypeVectorStores UsageType = "vector_stores"
	// UsageTypeCodeInterpreter represents code interpreter session usage
	UsageTypeCodeInterpreter UsageType = "code_interpreter"
)

Supported usage types for different OpenAI services.

type User

type User struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`
	// ID is the unique identifier for this user.
	ID string `json:"id"`
	// Name is the user's full name.
	Name string `json:"name"`
	// Email is the user's email address, used for authentication and communication.
	Email string `json:"email"`
	// Role defines the user's permissions within the organization.
	Role string `json:"role"`
	// AddedAt is the timestamp when this user was added to the organization.
	AddedAt UnixSeconds `json:"added_at"`
}

User represents a user account within an OpenAI organization. Users can have different roles and permissions within the organization.

func (*User) String added in v0.3.1

func (u *User) String() string

String returns a human-readable string representation of the User. It includes the user's ID, name, email, and role within the organization.

type UserAdded added in v0.2.11

type UserAdded struct {
	ID   string `json:"id"`
	Data struct {
		Role string `json:"role"` // Either "owner" or "member"
	} `json:"data"`
}

UserAdded represents the details for user.added events

type UserDeleted added in v0.2.11

type UserDeleted struct {
	ID string `json:"id"`
}

UserDeleted represents the details for user.deleted events

type UserUpdated added in v0.2.11

type UserUpdated struct {
	ID               string `json:"id"`
	ChangesRequested struct {
		Role string `json:"role"` // Either "owner" or "member"
	} `json:"changes_requested"`
}

UserUpdated represents the details for user.updated events

type VectorStoresUsage added in v0.3.1

type VectorStoresUsage struct {
	// Vectors is the number of vectors stored.
	Vectors int `json:"vectors"`

	// Size is the total storage space used in bytes.
	Size int `json:"size"`

	// Model identifies which vector storage model was used.
	Model string `json:"model"`
}

VectorStoresUsage represents the usage details for vector storage operations. This is used in the UsageDetails field of UsageRecord when Type is UsageTypeVectorStores.

type VectorStoresUsageBucket added in v0.3.1

type VectorStoresUsageBucket struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// StartTime is the start of this time bucket (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is the end of this time bucket (Unix timestamp).
	EndTime int64 `json:"end_time"`

	// Results contains the detailed vector stores usage data.
	Results []VectorStoresUsageResult `json:"results"`
}

VectorStoresUsageBucket represents a time-based bucket of vector stores usage data. Each bucket contains aggregated statistics about vector storage operations.

type VectorStoresUsageResponse added in v0.3.1

type VectorStoresUsageResponse struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// Data contains the list of vector stores usage buckets.
	Data []VectorStoresUsageBucket `json:"data"`

	// HasMore indicates if there are more records available.
	HasMore bool `json:"has_more"`

	// NextPage is the pagination token for fetching the next page.
	NextPage string `json:"next_page"`
}

VectorStoresUsageResponse represents the response from the vector stores usage endpoint. This provides detailed statistics about vector storage operations and capacity usage.

type VectorStoresUsageResult added in v0.3.1

type VectorStoresUsageResult struct {
	// Object identifies the type of this resource.
	Object string `json:"object"`

	// UsageBytes is the total storage space used in bytes.
	UsageBytes int `json:"usage_bytes"`

	// ProjectID identifies which project generated this usage.
	ProjectID string `json:"project_id"`
}

VectorStoresUsageResult represents a single vector stores usage record. This provides detailed information about vector storage capacity and data volume used.

Directories

Path Synopsis
cmd
mcp command
Package main provides an MCP (Model Context Protocol) server implementation for managing OpenAI organizations.
Package main provides an MCP (Model Context Protocol) server implementation for managing OpenAI organizations.
openai-orgs command
pkg
mcp
Package mcp implements the Model Context Protocol (MCP) server for OpenAI organization management.
Package mcp implements the Model Context Protocol (MCP) server for OpenAI organization management.

Jump to

Keyboard shortcuts

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