@nosana/api

TypeScript SDK for the Nosana API.

Installation

npm install @nosana/api

Quick Start

import { createNosanaApi, NosanaNetwork } from '@nosana/api';

// Create API instance
const api = createNosanaApi(NosanaNetwork.MAINNET, 'your-api-key');

// Use the API
const jobs = await api.jobs.list();
const credits = await api.credits.get();

Authentication

API Key

const api = createNosanaApi(NosanaNetwork.MAINNET, 'your-api-key');

SignerAuth (for vault operations)

SignerAuth enables wallet-based authentication and is required for deployment vault operations (balance, topup, withdraw).

import type { SignerAuth } from '@nosana/api';

const signerAuth: SignerAuth = {
  identifier: 'wallet-public-key',
  generate: async (message: string) => {
    // Sign message with wallet
    return signedMessage;
  },
  solana: {
    getBalance: async (address: string) => ({ SOL: 0, NOS: 0 }),
    transferTokensToRecipient: async (recipient, tokens) => { /* ... */ },
    deserializeSignSendAndConfirmTransaction: async (tx) => 'signature',
  },
};

const api = createNosanaApi(NosanaNetwork.MAINNET, signerAuth);

// Use vault methods
const vault = await api.deployments.vaults.create();
await vault.topup({ NOS: 100 });

Note: When using @nosana/kit, SignerAuth is automatically created from your wallet.

API Modules

api.auth — Authentication

| Method | Parameters | Returns | |--------|-----------|---------| | signMessage | message: string, options?: { includeTime?: boolean } | Promise<string> | | validateSession | cookieHeader?: string | Promise<ValidateSessionResponse> | | validateApiKey | apiKey: string | Promise<ValidateApiKeyResponse> |

api.user — API Key Management

| Method | Parameters | Returns | |--------|-----------|---------| | apiKeys.create | request: CreateApiKeyRequest | Promise<ApiKeyCreated> | | apiKeys.list | — | Promise<{ keys: ApiKey[]; total: number }> | | apiKeys.get | id: string | Promise<ApiKey> | | apiKeys.update | id: string, request: UpdateApiKeyRequest | Promise<ApiKey> | | apiKeys.delete | id: string | Promise<{ success: boolean }> |

api.jobs — Job Operations

| Method | Parameters | Returns | |--------|-----------|---------| | get | address: string | Promise<Job> | | getAll | request?: NosanaApiGetAllJobsRequest | Promise<Job[]> | | list | request: NosanaApiListJobRequest | Promise<NosanaApiListJobResponse> | | extend | { address, ...body }: NosanaApiExtendJobRequest | Promise<NosanaApiExtendJobResponse> | | stop | address: string | Promise<StopJobWithCreditsResponse> | | getRunning | — | Promise<Record<string, unknown>> | | getRunningNodes | request: JobRunningNodesRequest | Promise<Record<string, unknown>> | | getLongRunning | request?: JobLongRunningRequest | Promise<Record<string, unknown>> | | getStats | request?: JobStatsRequest | Promise<Record<string, unknown>> | | getStatsTimestamps | request?: JobStatsTimestampsRequest | Promise<Record<string, unknown>> | | getCount | request?: JobCountRequest | Promise<JobCountResponse> | | getBatch | request: JobBatchRequest | Promise<Job[]> |

api.credits — Credits & Invitations

| Method | Parameters | Returns | |--------|-----------|---------| | balance | — | Promise<Balance> | | claim | code: string | Promise<Record<string, unknown>> | | request | — | Promise<Record<string, unknown>> | | checkEligibility | — | Promise<Record<string, unknown>> | | invitations.get | token: string | Promise<Record<string, unknown>> | | invitations.claim | token: string | Promise<Record<string, unknown>> |

api.markets — GPU Markets & Pricing

| Method | Parameters | Returns | |--------|-----------|---------| | list | — | Promise<Market[]> | | get | market: string | Promise<Market> | | getRequiredResources | market: string | Promise<MarketRequiredResources> | | getPrices | — | Promise<Record<string, unknown>> | | getPrice | — | Promise<Record<string, unknown>> | | getGpuTypes | — | Promise<Record<string, unknown>[]> | | getDockerImages | — | Promise<Record<string, unknown>[]> |

api.deployments — Deployment Lifecycle

| Method | Parameters | Returns | |--------|-----------|---------| | create | deploymentBody: CreateDeployment | Promise<Deployment> | | get | deployment: string | Promise<Deployment> | | list | searchParams?: DeploymentsSearchParams | Promise<DeploymentListResult> | | pipe | deploymentIDorCreateObject, ...actions | Promise<Deployment> | | getJobDefinition | job: string | Promise<unknown> | | submitJobResults | job: string, results: JobResults | Promise<void> | | vaults.create | — | Promise<Vault> | | vaults.list | — | Promise<Vault[]> |

Deployment instance methods (returned by create, get, pipe):

| Method | Parameters | Returns | |--------|-----------|---------| | start | — | Promise<void> | | stop | — | Promise<void> | | archive | — | Promise<void> | | delete | — | Promise<void> | | getTasks | params?: PaginationParams | Promise<TaskListResult> | | getJob | job: string | Promise<unknown> | | getJobs | searchParams?: DeploymentJobsSearchParams | Promise<JobListResult> | | getRevisions | searchParams?: DeploymentRevisionsSearchParams | Promise<RevisionListResult> | | getEvents | searchParams?: DeploymentEventsSearchParams | Promise<EventListResult> | | createRevision | jobDefinition: JobDefinition | Promise<void> | | updateReplicaCount | replicas: number | Promise<void> | | updateTimeout | timeout: number | Promise<void> | | updateActiveRevision | active_revision: number | Promise<void> | | updateSchedule | schedule: string | Promise<void> | | updateMarket | market: string | Promise<void> | | updateRequirements | requirements: DeploymentRequirements \| null, market?: string \| null | Promise<void> | | duplicate | options?: DeploymentDuplicateOptions | Promise<Deployment> | | generateAuthHeader | — | Promise<unknown> | | ssh.keys | — | Promise<string[]> | | ssh.add | publicKeys: string \| string[] | Promise<DeploymentUpdateSshKeysResult> | | ssh.remove | publicKeys: string \| string[] | Promise<DeploymentUpdateSshKeysResult> |

api.templates — Deployment Templates

| Method | Parameters | Returns | |--------|-----------|---------| | list | — | Promise<Template[]> | | getAllGrouped | — | Promise<Record<string, unknown>> | | get | id: string | Promise<Template> | | getVariant | id: string, variantId: string | Promise<Template> |

api.hosts — Nodes & Hosts

| Method | Parameters | Returns | |--------|-----------|---------| | list | request?: NodeListRequest | Promise<Record<string, unknown>> | | get | id: string | Promise<Record<string, unknown>> | | getSpecs | id: string | Promise<Record<string, unknown>> | | getAvailableGpus | — | Promise<Record<string, unknown>> | | getStats | — | Promise<Record<string, unknown>> | | getQueuedNodes | request?: NodeQueuedRequest | Promise<Record<string, unknown>> | | getUptime | node: string, request?: NodeUptimeRequest | Promise<Record<string, unknown>> | | getByCountry | — | Promise<Record<string, unknown>> | | getAvailableHosts | request?: HostsFilterRequest | Promise<Record<string, unknown>> | | getFilters | request?: HostsFiltersOptionsRequest | Promise<Record<string, unknown>> | | getBenchmarkReport | request?: BenchmarkReportRequest | Promise<Record<string, unknown>> | | getTemplatePerformance | nodeId: string | Promise<Record<string, unknown>> | | getBenchmarkSummary | request?: BenchmarkSummaryRequest | Promise<Record<string, unknown>> |

api.reservations — GPU Models & Requirement Lookups

Read-only and unauthenticated. A requirement set maps a metric key to a value: a number is a minimum, a string or boolean must match exactly, a list is any of its values, and the GPU model is the name key.

| Method | Parameters | Returns | |--------|-----------|---------| | listGpus | — | Promise<NosanaGpuModels> | | getRequirementOptions | request?: NosanaRequirementOptionsRequest | Promise<NosanaRequirementOptions> | | findAvailable | request?: NosanaAvailableNodesRequest | Promise<NosanaAvailableNodes> |

api.node / api.jobs.get(job) — Node access

A node verifies the job owner's signature, and the client manager signs on the caller's behalf — so node access works under both wallet and API-key auth. It has the same shape unauthenticated, but then the node refuses what needs a signer.

| Call | Parameters | Returns | |--------|-----------|---------| | node(address) | address: string | Promise<NodeInfo> — a node's public info | | jobs.get(job) | job: string | Promise<Job & NodeJobApi> — the job's current indexer state flat-merged with its node job API |

jobs.get returns the job's state with its node job API on the same object, so (await api.jobs.get(id)).ssh.add(key) works. Until a node picks the job up, the node methods are present but fail saying so.

Node job methods (on await api.jobs.get(job), alongside the job's indexer fields):

| Method | Parameters | Returns | |--------|-----------|---------| | definition / setDefinition | — / definition: JobDefinition | Promise<JobDefinition> / Promise<void> | | results | — | Promise<FlowState> | | operations / operation / group | — / op: string / group?: string | Promise<NodeOperationStatuses> | | restartGroup / restartOperation | group: string / group: string, op: string | Promise<void> | | stopGroup / stopOperation / stop | group: string / group: string, op: string / — | Promise<void> | | endpoints | — | Promise<NodeJobEndpoints> | | stats | query?: NodeStatsQuery | Promise<NodeTaskStat[]> | | streamInfo / streamStats | handlers, query? | NodeStreamSubscription | | logs / status | handlers, filter?, options? | NodeStreamSubscription | | ssh.keys / ssh.add / ssh.remove | — / publicKey, { expiresAt? } / publicKey | see NodeJobSsh | | ssh.command | options?: SshCommandOptions | SshConnectionDescriptor | | terminal | options: NodeTerminalOptions | Promise<TerminalSession> |

stats, streamStats, logs, terminal and ssh.keys / ssh.add / ssh.remove go to the job's own runtime sidecar at https://<job>.<node domain> when its node runs one. The first such call checks for it (GET / answers the job address), and a job without one is served by its node, which has the same routes, and checked again after 30 s. Everything else always goes to the node.

api.stats — Platform Statistics

| Method | Parameters | Returns | |--------|-----------|---------| | get | — | Promise<Record<string, unknown>> | | getPrice | request?: StatsPriceRequest | Promise<unknown> | | getSpendingHistory | request: StatsHistoryRequest | Promise<Record<string, unknown>> | | getEarningHistory | request: StatsHistoryRequest | Promise<Record<string, unknown>> |

See API_ENDPOINTS.md for the full endpoint reference.

Development

npm install
npm test
npm run build

For more info go to learn.nosana.com