API Reference

The Solibo SDK is organized into sub-APIs, each corresponding to a functional area of the Solibo Home ecosystem.

Sub-APIs

The HomeApi instance provides access to various sub-APIs through the api field. Each sub-API corresponds to a tag in our OpenAPI specification.

For example:

  • api.board (Board management)
  • api.users (User profiles)
  • api.communication (Messaging and notifications)

All available sub-APIs can be discovered via your IDE’s auto-completion on the api object.

OpenAPI Specification

For the full list of endpoints and model definitions, you can refer to our OpenAPI specification: Swagger UI

Every operation in the downloaded OpenAPI specification is generated into both the raw KMP client and the JavaScript-native SoliboClient facade. Facade methods use a single named-parameter object and return the decoded body. client.raw preserves positional calls and HttpResponse<T> for code that needs status, headers, redirects, or downloads.

The packages have strict ownership boundaries: import SDK clients and models from @solibo/solibo-sdk, TanStack option factories and keys from @solibo/solibo-query, and hooks from @solibo/solibo-react. Most operations have named query factories and React hooks. For an operation without a dedicated wrapper, use openApiOperationQueryOptions(...) / openApiOperationMutationOptions(...) or useOpenApiOperationQuery(...) / useOpenApiOperationMutation(...). Run npm run audit:openapi after regenerating the client to verify coverage. See the changelog for migration examples.

Conversation State Mutations

The SDK conversation API also exposes batch state helpers for conversation workflows:

  • sdk.api.conversations.completeMultipleConversations(...)
  • sdk.api.conversations.reOpenMultipleConversations(...)
  • completeMultipleConversationsMutationOptions(...)
  • reOpenMultipleConversationsMutationOptions(...)
  • useCompleteMultipleConversations()
  • useReOpenMultipleConversations()

These helpers use the shared BatchConversationStateCommand shape with conversationIds.

Common Models

The SDK uses consistent data models across all platforms. These are located in no.solibo.oss.sdk.api.gen.models (Kotlin) or imported from @solibo/solibo-sdk (TypeScript).

Key models include:

  • AuthUser: Basic user information, either as PersonUser or ClientUser (service accounts).
  • Company: Information about a company, commonly housing companies in Solibo Home.
  • CompanyDetailed: Rich company metadata, including the sections summary object with count, businessCount, and residenceCount.
  • Building: Building metadata, including optional floor lists and Kartverket-derived details.
  • Person: Information about an individual.
  • Organization: Information about a legal entity (company, etc.).
  • Section: Building unit or section details, including nested building / floor metadata and section fractions.

Real Estate Models

  • CreateCompany now accepts buildings and detachedSections in the import-draft payloads exposed by the SDK, so company onboarding flows can carry building metadata and standalone sections together.
  • Section responses may include nested building and floor objects plus fields such as hNr, unitType, kitchenAccess, ownerFraction, and sectioningFraction.
  • CreateSection / CreateSectionCommand accept the richer section/building fields directly. UpdateSectionCommand updates the identity and fraction fields used most often by clients.
  • In the generated TypeScript props, the update-command field is named hnr, while create and response models use hNr. This matches the current backend spec.
  • @solibo/solibo-query and @solibo/solibo-react reuse the generated SDK models, so these field names stay aligned across Kotlin, direct TypeScript, query helpers, and React hooks.

Document Upload, Download, and Delete Wrappers

The TypeScript packages expose higher-level wrappers for document flows so consumers do not need to manually manage the backend’s signed upload and download URLs.

React (@solibo/solibo-react)

  • useUploadDocument(): Upload a private company document.
  • useUploadDocumentBelongsTo(): Upload a document linked to another resource via belongsToId.
  • useMultiUploadDocument(): Upload multiple files and receive Promise.allSettled(...) results.
  • usePublicUploadDocumentToConversation(): Upload a document to a public conversation.
  • useMultiUploadPublicDocumentToConversation(): Upload multiple public conversation files as one logical batch.
  • useCreateDocumentDirectory(): Create a document directory without uploading binary content.
  • useCreateDocumentReference(): Reuse an existing source document in another supported resource without uploading its binary again.
  • useGetDocumentURL(): Fetch a private document download URL as React Query data.
  • usePublicGetDocumentURL(): Resolve a public company document URL or a public conversation document URL.

@solibo/solibo-react is the React-specific layer. It exports hooks and SoliboProvider; import query factories and SDK models from their owning packages.

Framework-agnostic (@solibo/solibo-query)

  • uploadDocumentMutationOptions(...)
  • uploadDocumentBelongsToMutationOptions(...)
  • multiUploadDocumentMutationOptions(...)
  • publicUploadDocumentToConversationMutationOptions(...)
  • multiUploadPublicDocumentToConversationMutationOptions(...)
  • deletePublicConversationDocumentMutationOptions(...)
  • createDocumentDirectoryMutationOptions(...)
  • createDocumentReferenceMutationOptions(...)
  • getDocumentURLQueryOptions(...)

All file-upload mutations accept an optional onUploadProgress callback. It receives { file, loaded, total, fraction } so apps can drive progress bars without reimplementing the slingshot flow.

The query mutations adapt browser File objects and JS header collections internally, while the shared upload logic lives in KMP DocumentsApi. Low-level upload helpers are not part of the query package’s public surface; use a complete mutation factory or the SDK’s client.raw.api.documents escape hatch. Multi-file conversation mutations also create internal upload group ids so apps do not need to pass batching identifiers.

At the direct SDK level, Kotlin and TypeScript can both call DocumentsApi.uploadDocument(UploadDocumentRequest, onUploadProgress?). For concrete Kotlin, raw TypeScript, @solibo/solibo-query, and @solibo/solibo-react examples, see Usage Examples.

Integrated resource mutations

Use sdk.api.integratedDocuments when documents and their owning resource must become visible together. It provides create/update operations for homepage posts, practical information, newsletters, and normal conversation messages.

Inputs use DocumentInput.Upload(...) for new bytes and DocumentInput.Existing(...) for an existing source document. Upload tickets and binary transfers are prepared concurrently. One resource-specific backend request then creates document metadata and references, replaces inline slots, mutates the owner, and records side effects transactionally.

The matching framework-agnostic mutation factories are:

  • createHomepagePostWithDocumentsMutationOptions(...)
  • updateHomepagePostWithDocumentsMutationOptions(...)
  • createPracticalInformationWithDocumentsMutationOptions(...)
  • updatePracticalInformationWithDocumentsMutationOptions(...)
  • createNewsletterWithDocumentsMutationOptions(...)
  • updateNewsletterWithDocumentsMutationOptions(...)
  • createConversationMessageWithDocumentsMutationOptions(...)

@solibo/solibo-react exposes corresponding use*WithDocuments() hooks. Browser inputs accept { file }, { fileName, bytes }, or { sourceDocumentId }, plus optional image, attachments, and inlineDocuments fields. The byte form accepts Int8Array, Uint8Array, or ArrayBuffer, so non-browser callers do not need to construct a File. The wrappers invalidate both document caches and the relevant homepage, newsletter, or conversation caches after success.

If upload preparation fails, successfully uploaded temporary binaries are deleted through the authenticated ticket-abort endpoint and rollback failures are exposed through IntegratedDocumentMutationException.rollbackFailures. A definitive backend rejection also triggers cleanup. Transient finalization failures are retried with the same tickets and idempotency key. If the final response is lost and the commit outcome cannot be known, binaries are deliberately retained and the exception exposes the generated idempotencyKey for a safe retry. Aborting a ticket can never delete a ticket that finalization has already consumed. Cancellation while the finalization request is in flight throws IntegratedDocumentMutationCancellationException, which remains a coroutine cancellation exception and exposes the generated idempotencyKey with outcomeUnknown = true for an explicit retry. Cancellation during upload aborts every known ticket before propagating the same exception with phase = "UPLOAD", outcomeUnknown = false, and any failed aborts in rollbackFailures.

Safe marker helpers are exported for canonical IDs and temporary slots: inlineDocumentImage, inlineDocumentLink, inlineDocumentImageSlot, and inlineDocumentLinkSlot. Image helpers accept optional InlineDocumentImageOptions (width, height, title, className, and style). Link helpers accept optional InlineDocumentLinkOptions (title, target, className, and style). Inline styles are authoritative only after backend sanitization; unsupported CSS and URL-bearing values are removed.

Upload behavior

For file uploads, the wrappers hide the backend’s two-step “slingshot” flow:

  1. They convert the browser File into a KMP UploadBinaryRequest.
  2. They prepare the required request headers through DocumentsApi.createUploadHeaders(...).
  3. They call the SDK’s createDocument(...) or createDocumentBelongsTo(...) endpoint.
  4. They read the signed upload and verification headers from the SDK response.
  5. They finish the storage upload and verification through DocumentsApi.completeSignedUpload(...).

For the standard private company-document path, DocumentsApi.uploadDocument(...) wraps the whole flow directly and also accepts an optional upload-progress callback.

When onUploadProgress is provided, browser environments receive incremental byte progress during the storage PUT. Other environments still receive start/end progress updates from the same callback.

You normally do not need to call the raw backend upload URL yourself. Use the wrappers unless you are implementing a custom upload flow around a signed-upload endpoint.

For directory creation, use useCreateDocumentDirectory() or createDocumentDirectoryMutationOptions(...) instead of the file upload wrappers.

Download behavior

  • useGetDocumentURL() and getDocumentURLQueryOptions(...) use non-redirect mode and return a UrlWrapper body containing { url }.
  • usePublicGetDocumentURL() is imperative rather than React Query-based:
    • getDocumentURL(documentId) resolves a public company document URL.
    • getDocumentURL(conversationId, documentId) resolves a public conversation document URL.
  • Any size or fields options passed into usePublicGetDocumentURL(...) are forwarded to both public company and public conversation document requests.
  • These wrappers intentionally return the signed URL so the app can decide whether to open, preview, or download it.

Delete behavior

DocumentsApi.deleteDocument(...) only calls the Solibo API delete endpoint. It does not follow a storage Location response or delete the underlying object directly. The Solibo API soft-deletes the document metadata and may return a signed storage delete URL in Location. Callers should send DELETE to that URL only when the underlying binary must also be permanently deleted; otherwise the binary is retained.

Paged Lists

All collection endpoints return a PagedList<T> wrapper instead of a plain array. This applies to both the Kotlin SDK and the TypeScript layer.

Structure 

PagedList<T>
  .items   — the current page of results (List<T> / T[])
  .meta    — metadata, including .count (total items on this page)
  .paging  — cursor pagination tokens:
               .next     — pass as pageToken to fetch the next page ("END_OF_LIST" means no more pages)
               .previous — token for the previous page

Kotlin 

val response = mockApi.task.indexTasks(1L).body()
val tasks: List<Task> = response.items
val total: Long = response.meta.count ?: 0L
val nextToken: String? = response.paging.next

React / TypeScript (via hooks)

Paged list hooks use TanStack’s useInfiniteQuery. Each call appends a new page to data.pages:

import { useIssues } from '@solibo/solibo-react'

function IssueList({ companyId }: { companyId: number }) {
  const { data, fetchNextPage, hasNextPage } = useIssues({ companyId })

  const allIssues = data?.pages.flatMap(page => page.items) ?? []

  return (
    <>
      {allIssues.map(issue => <div key={issue.id.toString()}>{issue.title}</div>)}
      {hasNextPage && <button onClick={() => fetchNextPage()}>Load more</button>}
    </>
  )
}

When calling the facade directly (outside a hook), collection results are already JavaScript arrays:

const body = await client.api.task.indexTasks({ companyId })
const tasks = body.items

Field Projections

Most read endpoints accept an optional fields query parameter that limits which fields are returned in the response. This reduces payload size when only a subset of data is needed.

Kotlin 

// Only include company and feed fields in the homepage response
val homepage = sdk.api.homepage.showHomepage(companyId, fields = "company,feed").body()

TypeScript (via hooks)

Pass fields through the hook’s params object:

import { useHomepage } from '@solibo/solibo-react'

const { data } = useHomepage({ companyId, fields: 'company,feed' })

Omitting fields returns the full object. Consult the Swagger UI for the available field names per endpoint.

Platform-Specific Details

Kotlin (Multiplatform)

Models are data classes with @Serializable annotations. All API calls are suspend functions.

Web (JS/TS)

Models are TypeScript interfaces. API calls return Promise objects. @solibo/solibo-react provides React hooks, while @solibo/solibo-query provides the underlying framework-agnostic query and mutation option factories.

Solibo AS