Get Started

Theneo SDK

The Theneo SDK is a TypeScript/JavaScript package for calling the Theneo API from your own apps.

Install

Bash

   npm install @theneo/sdk

Usage

Import the classes you need, create a Theneo instance with your API key, and call its methods:

JavaScript

   import { Theneo, TheneoOptions, Result, Workspace, ProjectSchema, CreateProjectOptions } from "@theneo/sdk";

// Define Theneo options
const options: TheneoOptions = {
  apiKey: "YOUR_API_KEY"
};

// Create a Theneo instance
const theneo = new Theneo(options);

// List workspaces
async function listWorkspaces() {
  const result: Result = await theneo.listWorkspaces();
  if (result.ok) {
    const workspaces: Workspace[] = result.unwrap();
    console.log("Workspaces:", workspaces);
  } else {
    console.error("Error:", result.unwrap());
  }
}

// Create a new project
async function createProject() {
  const projectOptions: CreateProjectOptions = {
    name: "My Project",
    workspace: { key: "workspace-key" },
    publish: true,
    isPublic: true,
    data: {
      // Specify the data source using ONE of the following:
      // file: '/path/to/api-documentation.json',
      // link: 'https://example.com/api-documentation.json',
      // text: 'API documentation content as a string',
      // postman: { apiKey: 'YOUR_POSTMAN_API_KEY', collectionIds: ['collection-id-1'] },
    } as ApiDataInputOption
  };

  const result: Result = await theneo.createProject(projectOptions);
  if (result.ok) {
    console.log("Created Project:", result.unwrap());
  } else {
    console.error("Error:", result.unwrap());
  }
}

listWorkspaces();
createProject();

Import API documentation

Use importProjectDocument to import a spec into an existing project:

JavaScript

   import { Theneo, TheneoOptions, Result, ImportProjectOptions, ImportResponse, ApiDataInputOption } from "@theneo/sdk";

const options: TheneoOptions = { apiKey: "YOUR_API_KEY" };
const theneo = new Theneo(options);

const importOptions: ImportProjectOptions = {
  projectId: "project-id",   // Replace with the actual project ID
  publish: true,             // Publish the imported data
  data: {
    // file / link / text / postman — specify one
  } as ApiDataInputOption
};

async function importApiDocumentation() {
  const result: Result = await theneo.importProjectDocument(importOptions);
  if (result.ok) {
    console.log("Imported API Documentation:", result.unwrap());
  } else {
    console.error("Error:", result.unwrap());
  }
}

importApiDocumentation();

In this example you create a Theneo instance with your API key, define importOptions (replacing project-id with your actual project ID), choose one data source inside data (file, URL, text, or Postman collection), set publish: true, and call importProjectDocument. Replace all placeholder values with your real API key and project details before running.

API reference

TheneoOptions (interface)

Options for initializing the SDK.

apiKey?: string — API key for the Theneo application.
apiClientName?: string — name of the client making the call (default theneo-sdk:${SDK_VERSION}).
baseApiUrl?: string — Theneo API URL.
baseAppUrl?: string — Theneo app URL.

Theneo (class)

The main class for interacting with the Theneo API.

Methods

listWorkspaces(role?: UserRole): Promise> — lists workspaces available to a user.
listProjects(): Promise> — lists user projects.
deleteProjectById(projectId: string): Promise> — deletes a project by ID.
publishProject(projectId: string): Promise> — publishes a project.
getPreviewProjectLink(projectId: string): string — returns a preview link for a project.
importProjectDocument(options: ImportProjectOptions): Promise> — imports documentation to an existing project.
createProject(options: CreateProjectOptions): Promise> — creates a new project.
getDescriptionGenerationStatus(projectId: string): Promise> — gets description-generation status.
waitForDescriptionGeneration(projectId, progressUpdateHandler?, retryTime?, maxWaitTime?): Promise> — waits for description generation to finish.
static listPostmanCollections(postmanApiKey: string): Promise> — lists Postman collections for an API key.

DescriptionGenerationType (enum)

FILL — generate descriptions only where missing.
OVERWRITE — overwrite existing descriptions.
NO_GENERATION — do not generate descriptions.

DescriptionGenerationProgressHandler (type)

A callback that receives the progress percentage of description generation.

PostmanImportOptions (interface)

apiKey: string — Postman API key.
collectionId: string[] — Postman collection IDs to import.

WorkspaceOption (interface)

key?: string — workspace key.
id?: string — workspace ID.

CreateProjectOptions (interface)

name: string — project name.
workspace?: WorkspaceOption — workspace to create in (default: user's default).
publish?: boolean — publish after creation (default false).
isPublic?: boolean — make public (default false).
data?: ApiDataInputOption — API documentation data.
sampleData?: boolean — create with sample data.
descriptionGenerationType?: DescriptionGenerationType — description generation type.
progressUpdateHandler?: DescriptionGenerationProgressHandler — progress callback.

ApiDataInputOption (interface)

Specify only one of the following:

file?: fs.PathLike — path to a documentation file.
link?: URL — URL to a documentation file.
text?: string — documentation as a string.
postman?: PostmanImportOptions — a Postman collection.

ImportOption (enum)

ENDPOINTS_ONLY — import only endpoints.
OVERWRITE — overwrite existing data.
MERGE — merge with existing data.

ImportProjectOptions (interface)

projectId: string — project ID.
publish: boolean — publish the imported data.
data: ApiDataInputOption — documentation data.
importOption?: ImportOption — import option.

PublishProjectResponse (interface)

projectKey: string, baseUrlRequired: boolean, companySlug: string, publishedPageUrl: string.

CompanySchema (interface)

id, name, slug, corporateId, createdAt, updatedAt, createdBy.

ProjectSchema (interface)

id, name, key, isPublic, companyId, createdAt, company: CompanySchema.

CreateOtherTypeOfDocOptions (interface)

Options for creating non-API documentation.

docType: string — the documentation type.
gettingStartedSections? — { introduction, prerequisites, quickStart, resources }.
sdk? — { overview, supportedLibraries, sampleCode, troubleshooting }.
faq? — { generalInfo, authentication, usage, billing }.

CreatedProjectStatusEnum (enum)

CREATED, STARTED, FINISHED, ERROR, CREATED_WITHOUT_AI_GENERATION.

CreateProjectResponse (interface)

projectId: string, publishData?: PublishProjectResponse.

ProjectCreationStatusResponse (interface)

name, key, creationStatus: CreatedProjectStatusEnum, descriptionGenerationProgress: number, updatedAt.

ImportResponse (interface)

collectionId: string, publishData?: PublishProjectResponse.

UserRole (enum)

ADMIN, EDITOR.

Workspace (interface)

workspaceId, name, slug, role: UserRole, isDefault, isCorporate, isSubscribed.

Result, Ok, Err

ResultImp is an abstract class representing an operation that either succeeds with a value of type T or fails with an error of type E. Use Ok(value) and Err(error?) to construct results.

Methods include:

unwrap() — returns the success value, or throws on error.
unwrap(ok, err?) — applies functions based on success or error.
map(ok, err?) — transforms into a new result.
chain(ok, err?) — chains functions that produce new results.

OkResult holds value: T; ErrResult holds error: E.

ResponseSchema (interface)

data: T — the response payload.
message: string — a message associated with the response.

Sections