Make your first SDK request

Read a layout with JavaScript.

Source 0.1.0 Private source package

Before you begin

Hosted SDK distribution is planned but not available. You need authorised access to private source SDK 0.1.0 and an approved development environment. Public installation and self-service integration registration are not available yet.

Choose an account and layout

An account owns your railway records; a layout selects the railway you are reading. Use development identifiers for which your integration has current access. An identifier alone does not grant permission.

Saved definitions and settings describe your collection. Live commands operate it and need a separate, deliberate action. This first request only reads the latest known state.

Choose your client

This JavaScript example is for a named non-browser integration. Supply apiBaseUrl from your approved environment and getAccessToken from your identity adapter. It returns the current token; acquisition, refresh and sign-out remain with your adapter.

Browser integrations need their approved audience and identity flow. The narrow public client is for guest access. Keep terminal credentials out of browser pages. Node is needed for the optional terminal starter, not for the HTTP API.

Configure a client and read a layout

Call readLayoutItems(apiBaseUrl, getAccessToken, accountId, layoutId) from your integration. Use the returned items in your own interface; an empty list is valid.

import { createRailDeckDirectIntegrationClient } from '@raildeck/frontend-sdk/direct-integration';

/**
 * Reads the latest known items for one authorised layout.
 * @param apiBaseUrl - Approved API origin for your development environment.
 * @param getAccessToken - Your adapter returning the current approved access token.
 * @param accountId - Account your integration may access.
 * @param layoutId - Selected layout within that account.
 * @returns The decoded state items; an empty array is a valid result.
 */
export async function readLayoutItems(apiBaseUrl, getAccessToken, accountId, layoutId) {
  const client = createRailDeckDirectIntegrationClient({
    baseUrl: apiBaseUrl,
    getAccessToken,
  });

  const result = await client.currentState.getLayoutSnapshot(accountId, layoutId, {
    timeoutMs: 15000,
  });

  if (result.currentState.accountId !== accountId || result.currentState.layoutId !== layoutId) {
    throw new Error('The response belongs to a different account or layout.');
  }

  return result.currentState.items;
}

Await the function inside your caller’s error handling. A refused or malformed response rejects the call; it is never turned into an empty successful result. The SDK sends one request with a 15-second timeout and performs no automatic retry. See commands and errors for error kinds and uncertain outcomes.

Make the same read over HTTP

Any language with an HTTPS client can make this request. Replace the double-braced values with your approved API origin, URL-encoded path identifiers and current access token. No request body is sent.

GET {{apiBaseUrl}}/accounts/{{accountId}}/layouts/{{layoutId}}/current-state
Authorization: Bearer {{accessToken}}
Accept: application/json

Read the JSON response

A representative 200 OK response for an empty layout, with fictional identifiers. JavaScript reads result.currentState.items; other clients must validate the schema, account and layout before using the data.

{
  "schemaVersion": 1,
  "currentState": {
    "accountId": "example-account",
    "layoutId": "example-layout",
    "items": []
  }
}

Use a bounded timeout and handle non-success responses before decoding JSON. Keep bearer tokens out of URLs and logs. This request needs current layout-read permission; its response describes known state and does not prove physical movement. Continue with feature examples or the cancellable TypeScript read.