ruLog in to Senler

API SDK

What it is

@aisenler/sdk-fetch is a typed client for the public Senler AI API. It is generated from the OpenAPI specification and provides the AiSenlerClient class, response models, and separate method groups such as client.projects, client.agents, and client.apps.

The SDK is intended primarily for server-side integrations. It also runs in an environment with global fetch, but an arbitrary external website cannot call the production API unless its origin is allowed by the CORS policy. Never put a project API key or Client Secret in browser code.

Installation

Install the current published version from GitHub using a pinned tag:

npm install github:SenlerBot/Senler-io-sdk#v0.1.16

The package requires Node.js 18+ and includes TypeScript declarations. The pinned tag prevents a newly generated SDK contract from being pulled during the next dependency installation.

Authorization

Pass only the token value to accessToken, without the Bearer prefix. The SDK adds the Authorization: Bearer <token> header to every request.

Two token sources are supported:

  • a project API key in the senler_sk_... format for an integration with one project;
  • an application OAuth access token for access granted by a user through OAuth.

Available methods depend on the token scope and permissions. A user OAuth token is additionally restricted by the user's current permissions in the target project or developer application.

First request

Example for a project API key or project-scoped OAuth token:

import { AiSenlerClient } from "@aisenler/sdk-fetch";

const client = new AiSenlerClient({
  accessToken: process.env.SENLER_API_TOKEN!,
});

const currentProject = await client.projects.getMe();

const agents = await client.agents.list({
  projectId: currentProject.project.id,
  limit: 20,
});

An external integration does not need X-Session-Id: that header belongs to a cabinet session and is not part of the generated SDK method parameters.

Methods and types

A client group corresponds to an API section, and a method corresponds to an operation in the public OpenAPI specification. For example:

  • client.projects covers projects;
  • client.agents covers agents;
  • client.dialogsMessaging covers dialog messages;
  • client.apps covers developer applications;
  • client.appDocumentation covers developer application documentation.

These are examples, not a complete catalog. Current groups and signatures are available through TypeScript completion for the installed SDK version. Endpoint behavior, required parameters, and permissions are documented in the API reference.

Method parameters are passed as one camelCase object. The SDK converts property names to the API JSON format and converts responses into typed models. For example, idempotencyKey is sent as idempotency_key. If a required parameter is missing, TypeScript reports it during compilation and the runtime check throws RequiredError.

Starting with v0.1.15, updating a developer application is split by purpose. Replace the former client.apps.appsUpdate with client.apps.updateGeneralSettings for the name, description, and website, client.apps.updateToolsSettings for agent tools, and client.apps.updateEmbeddedPageSettings for the embedded page. Each method accepts only the fields from its section, so changing one form does not overwrite adjacent settings.

For available model objects, supported_server_binding_modes lists the MCP modes compatible with the model and its active provider connections. Use this field when selecting an agent model instead of hard-coding compatibility in an integration.

Application Action Contract

In v0.1.16, the package gained separate entry points for application actions. Shared types, the metadata builder, and OpenAPI validation are available from @aisenler/sdk-fetch/app-actions, while NestJS decorators are exported from @aisenler/sdk-fetch/app-actions/nest. NestJS remains an optional peer dependency and is not loaded by the main SDK client.

After generating OpenAPI, validate the local file or available URL with the same package version:

npx senler-app validate-openapi ./openapi.json

The command lists x-senler-app-action contract errors, exits with a nonzero code when it finds an error, and can be used in CI. The detailed workflow, supported contexts, and decorator example are provided in Application actions.

Client configuration

The constructor supports these parameters:

  • accessToken is the required API key or OAuth access token;
  • baseUrl is the API address and defaults to https://api.senler.io; an override is normally useful only for development and tests;
  • fetchApi supplies a custom fetch implementation when required by a runtime or test.

If the token is refreshed outside the SDK, replace it before the next request:

client.accessToken = newAccessToken;

Automatic OAuth token refresh

Automatic refresh is intended for a server-side OAuth integration. Provide all three values, refreshToken, clientId, and clientSecret, and persist the new tokens in onTokenRefreshed:

const client = new AiSenlerClient({
  accessToken: "access_token",
  refreshToken: "refresh_token",
  clientId: "client_id",
  clientSecret: process.env.SENLER_CLIENT_SECRET!,
  onTokenRefreshed: async (newAccessToken, newRefreshToken) => {
    await saveTokensAtomically(newAccessToken, newRefreshToken);
  },
});

After a 401 response, the SDK calls POST /api/apps/oauth/token once, updates the tokens, waits for onTokenRefreshed, and retries the original request. It does not refresh a token proactively based on its expiration time. A partial refresh configuration is rejected by the TypeScript types.

The token endpoint rotates the refresh token after a successful refresh, so persist the access token and refresh token together. Client Secret and the refresh token must remain on the server.

Errors

The SDK exports three main error classes:

  • ResponseError means the API returned an unsuccessful HTTP status; the original Response is available as error.response;
  • FetchError means the request did not receive a response, for example because of a network error;
  • RequiredError means a required method parameter was omitted.
import {
  FetchError,
  RequiredError,
  ResponseError,
} from "@aisenler/sdk-fetch";

try {
  await client.projects.getMe();
} catch (error) {
  if (error instanceof ResponseError) {
    const details = await error.response.clone().json().catch(() => null);
    console.error(error.response.status, details);
  } else if (error instanceof RequiredError) {
    console.error("Missing parameter:", error.field);
  } else if (error instanceof FetchError) {
    console.error("Network error:", error.cause);
  } else {
    throw error;
  }
}

For a 401 response, check whether the token is current. For 403, check token permissions and user permissions. For an entity error, verify projectId, the resource ID, and the token scope.

Reference materials

Previous
Webhooks
Next
Application Through User MCP