Lambda Cloud API LogoLambda Cloud API Logo

Lambda Cloud API

The Lambda Cloud API provides a set of REST API endpoints you can use to create and manage your Lambda Cloud resources.

Requests to the API are generally limited to one request per second. Requests to the /instance-operations/launch endpoint are limited to one request per 12 seconds, or five requests per minute.

Download OpenAPI spec 1.10.0

Response types and formats

The format of each response object depends on whether the request succeeded or failed.

Success responses

When a request succeeds, the API returns a response object in the following format. <PAYLOAD> represents the endpoint-specific data object returned as part of the response object.

{
    "data": <PAYLOAD>
}

Error responses

When a request fails, the API returns an error response object in the following format:

{
    "error": {
        "code": string,
        "message": string,
        "suggestion": string?,
        "request_id": string?
    }
}
  • code: A machine- and human-readable error code specific to a particular failure mode.
  • message: An explanation of the error.
  • suggestion: When present, a suggestion for how to address the error.
  • request_id: Uniquely identifies the request that produced the error. Quote it when contacting support.
info
Note

When handling errors, avoid relying on the values of message or suggestion, as these values are subject to change. Instead, use the value of code.

Provider errors

In some cases, you might receive errors that come from upstream services/providers rather than directly from Lambda services. You can identify these errors by their error code prefix, provider/.

Common provider errors include:

  • Network outages or connectivity issues
  • Service unavailability
  • Quota limitations or resource exhaustion

An example of a typical service unavailability error:

{
  "error": {
    "code": "provider/internal-unavailable",
    "message": "Provider unavailable",
    "suggestion": "Try again shortly"
  }
}

Outgoing webhooks

Lambda can send webhook notifications to your URL when support ticket events occur, enabling near real-time integration with your systems.

Event types

  • ticket.created - A support ticket was created.
  • ticket.status_changed - A support ticket's status was updated, and the ticket remains open.
  • ticket.resolved - A support ticket's status was set to solved, or the ticket was closed.

Payload structure

All webhook payloads follow this structure:

{
  "id": "a3b7c9d1e5f642a8b0c2d4e6f8a0b2c4",
  "object": "event",
  "type": "ticket.created",
  "created": 1700000000,
  "api_version": "2025-11-18",
  "data": {
    "object": "ticket",
    "id": "f1e2d3c4b5a647869708192a3b4c5d6e",
    "subject": "Issue with instance 0920582c7ff041399e34823a0be62549",
    "description": "Detailed description of the issue...",
    "request_type": "incident",
    "severity": "sev_2",
    "status": "new",
    "created_at": "2024-11-15T10:00:00+00:00",
    "updated_at": "2024-11-15T10:00:00+00:00",
    "instance_ip": "192.168.1.100",
    "instance_id": "0920582c7ff041399e34823a0be62549",
    "cluster_id": null,
    "source": "api"
  }
}

Webhook authentication

Webhook requests include a Bearer token in the Authorization header for authentication:

Authorization: Bearer <token>

Authentication

The Lambda Cloud API uses API keys to authenticate incoming requests. You can generate a new API key pair or view your existing API keys by visiting the API keys page in the Lambda Cloud dashboard.

In general, Lambda recommends passing an HTTP Bearer header that contains your API key:

Authorization: Bearer <YOUR-API-KEY>

Authenticating with curl

Pass your API key in the Authorization header using the Bearer scheme. For example:

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer <YOUR-API-KEY>'

For backward compatibility, the API also accepts an HTTP Basic header, which supports curl's -u flag (the API key is sent as the username with an empty password). New integrations should prefer the Bearer header shown above.

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
  --header 'accept: application/json' \
  --user '<YOUR-API-KEY>:'
warning
Important

If you make a request without including a supported Authorization header, the request will fail.

Trying out the API

You can also try Lambda Cloud API endpoints directly from the API browser. To configure this feature:

  1. Visit the API keys page in the Lambda Cloud dashboard.
  2. Generate an API key, and then copy the key.
  3. Paste your API key below, and then click Set key.

After you set the key, visit the Parameters & Request sample section of the endpoint you want to test, fill in the relevant parameters, and then click Send request to make a request. The response status and object will appear in the corresponding Response section.

Account

The account the requester belongs to.

Retrieve current account's details

GET /api/v1/account

Retrieves information about the requester's account.

Parameters

There are no parameters for this endpoint.

Response:200

  • data Account required
    • id string required

      The unique identifier for the account.

    • name string optional

      The name of the account.

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/account' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "name": "string"
  }
}
Live
Send a request to see the response.

API keys

API keys by ID, independent of the identity that owns them.

List API keys in the account

GET /api/v1/api-keys

Lists every API key in the account across all identities, with the owning identity on each key. Revoked API keys are never returned. Requires the user-identity API-key read permission on the account; service-identity keys are included only when the caller also holds the service-identity API-key read permission, and requesting them explicitly without it is rejected.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • name string optional

    Return only API keys with exactly this name.

  • status enum optional

    Filter API keys by status. If omitted, active and expired keys are returned.

    • Possible values:
      • "active"
      • "expired"
  • identity_id string optional

    Return only API keys owned by this identity.

  • identity_type enum optional

    Return only API keys owned by identities of this type.

    • Possible values:
      • "user"
      • "service"

Response:200

  • data array of ApiKeyResponse required
    • ApiKeyResponse
      • id string required

        The unique identifier (ID) of the API key.

      • name string required

        The user-defined name of the API key.

      • identity_id string required

        The unique identifier (ID) of the identity that owns the API key.

      • created_at string required

        The date and time at which the API key was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • expires_at (string | null) required

        The date and time at which the API key will expire. Formatted as an ISO 8601 timestamp. Returns null if no expiration period was set during key creation.

        Any of
        • string
          • Format: date-time
        • null
      • last_used_at (string | null) required

        The date and time at which the API key was last used. Formatted as an ISO 8601 timestamp. Returns null if the key hasn't been used.

        Any of
        • string
          • Format: date-time
        • null
      • status enum required

        The current status of the API key.

        • Possible values:
          • "active"
          • "expired"
      • identity_type enum optional

        Whether the owning identity is a user or a service identity.

        • Possible values:
          • "user"
          • "service"
      • identity_display_name string optional

        The owning identity's display name: a user's full name or a service identity's name. Empty when the identity has no name on record.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/api-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "identity_id": "ddaedf1b7a0e41ac981711504493b242",
      "created_at": "1970-01-01T00:00:00.000Z",
      "expires_at": "1970-01-01T00:00:00.000Z",
      "last_used_at": "1970-01-01T00:00:00.000Z",
      "status": "active",
      "identity_type": "user",
      "identity_display_name": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Retrieve details about an API key

GET /api/v1/api-keys/{key_id}

Retrieves metadata for the specified API key.

Path Parameters

  • key_id string required

    The unique identifier (ID) of the API key.

Response:200

  • data ApiKeyResponse required
    • id string required

      The unique identifier (ID) of the API key.

    • name string required

      The user-defined name of the API key.

    • identity_id string required

      The unique identifier (ID) of the identity that owns the API key.

    • created_at string required

      The date and time at which the API key was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • expires_at (string | null) required

      The date and time at which the API key will expire. Formatted as an ISO 8601 timestamp. Returns null if no expiration period was set during key creation.

      Any of
      • string
        • Format: date-time
      • null
    • last_used_at (string | null) required

      The date and time at which the API key was last used. Formatted as an ISO 8601 timestamp. Returns null if the key hasn't been used.

      Any of
      • string
        • Format: date-time
      • null
    • status enum required

      The current status of the API key.

      • Possible values:
        • "active"
        • "expired"
    • identity_type enum optional

      Whether the owning identity is a user or a service identity.

      • Possible values:
        • "user"
        • "service"
    • identity_display_name string optional

      The owning identity's display name: a user's full name or a service identity's name. Empty when the identity has no name on record.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/api-keys/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "string",
    "name": "string",
    "identity_id": "ddaedf1b7a0e41ac981711504493b242",
    "created_at": "1970-01-01T00:00:00.000Z",
    "expires_at": "1970-01-01T00:00:00.000Z",
    "last_used_at": "1970-01-01T00:00:00.000Z",
    "status": "active",
    "identity_type": "user",
    "identity_display_name": "string"
  }
}
Live
Send a request to see the response.

Delete an API key

DELETE /api/v1/api-keys/{key_id}

Deletes the specified API key. To delete an API key that belongs to an identity other than your own, you must have a role that contains the relevant permissions.

Path Parameters

  • key_id string required

    The unique identifier (ID) of the API key.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/api-keys/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

Audit Events

Get audit events

GET /api/v1/audit-events

Retrieves a list of audit events that have occurred in your account. To view the full catalog of possible audit events, visit Access and security > Audit logs in the Lambda Cloud documentation.

Query Parameters

  • start string optional

    An ISO 8601 timestamp defining the start of the time range to query, inclusive. If omitted, the response starts at the earliest available event.

    • Format: date-time
  • end string optional

    An ISO 8601 timestamp defining the end of the time range to query, inclusive. If omitted, the response ends at the most recent event.

    • Format: date-time
  • page_token string optional

    The token returned by the previous API response to retrieve the next page of results.

  • resource_type string optional

    The resource type to filter by. By default, all available resource types are retrieved.

Response:200

  • data array of AuditEvent required
    • AuditEvent

      Audit event in the account's audit log. To view the full catalog of possible audit events, visit Access and security > Audit logs in the Lambda Cloud documentation.

      • service_name string required

        The service in which the action was performed.

      • resource_name string required

        The type of resource that was affected.

      • action string required

        The action that was performed.

      • catalog_version string required

        The version of the event catalog schema.

      • event_id string required

        The unique identifier (ID) for this audit event.

      • event_time string required

        The UTC timestamp for when the event occurred (ISO 8601 format).

      • actor_lrn (string | null) required

        The Lambda Resource Name (LRN) of the actor who performed the action. This is the stable identifier for the actor; emails and display names can change or be reassigned over time.

        Any of
        • string
        • null
      • actor_email (string | null) required

        The email address of the actor, resolved at read time from the actor's identity. Reflects the current email, not the email at the time of the event. null for service identities (which have no email), system-generated events, and actors that no longer resolve to an identity in this account.

        Any of
        • string
        • null
      • actor_display_name (string | null) required

        A human-readable name for the actor, resolved at read time: the user's full name, or the display name of a service identity. null when unavailable or when the actor no longer resolves to an identity in this account.

        Any of
        • string
        • null
      • resource_lrns array of string required

        The Lambda Resource Names (LRNs) of the resources affected by this action.

        • string
      • resource_owner_lrn (string | null) required

        The Lambda Resource Name (LRN) of the account that owns the affected resources.

        Any of
        • string
        • null
      • request_api_key_lrn (string | null) required

        The Lambda Resource Name (LRN) of the API key used to authenticate the request, if applicable.

        Any of
        • string
        • null
      • workspace_lrn (string | null) required

        The Lambda Resource Name (LRN) of the workspace the affected resources belong to, if applicable.

        Any of
        • string
        • null
      • client_ip (string | null) required

        The IP address the request originated from. Shows lambda-internal for actions performed by Lambda staff. null for system-generated events and events recorded before this field was introduced.

        Any of
        • string
        • null
      • client_user_agent (string | null) required

        The User-Agent header supplied by the client that made the request. This value is client-controlled and informational only. null for system-generated events and events recorded before this field was introduced.

        Any of
        • string
        • null
      • surface (string | null) required

        The surface the request came through: console (logged-in browser session), api (API key), or system (generated by Lambda systems without a request). null when the surface could not be determined (for example, unauthenticated requests) and for events recorded before this field was introduced.

        Any of
        • string
        • null
      • result (AuditResult | null) required

        The result of the audited action, including its status and the HTTP status code when the action originated from an API request. null for events recorded before this field was introduced.

        Any of
        • AuditResult

          The result of an audited action.

          • status enum required

            The result of an audited action, open to future status values.

            • Possible values:
              • "success"
              • "failure"
          • status_code (integer | null) optional
            Any of
            • integer
            • null
        • null
      • additional_details object required

        Additional event-specific details. The exact keys returned vary by event type.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/audit-events' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "service_name": "cloud",
      "resource_name": "api_key",
      "action": "created",
      "catalog_version": "2025-09-06",
      "event_id": "0123456789abcdef0123456789abcdef",
      "event_time": "2025-09-15T10:30:45.123456Z",
      "actor_lrn": "lrn:cloud:identity:00112233445566778899aabbccddeeff",
      "actor_email": "alice@example.com",
      "actor_display_name": "Alice Example",
      "resource_lrns": [
        "lrn:cloud:api_key:ffeeddccbbaa99887766554433221100"
      ],
      "resource_owner_lrn": "lrn:cloud:account:fedcba9876543210fedcba9876543210",
      "request_api_key_lrn": "lrn:cloud:api_key:0f1e2d3c4b5a69788796a5b4c3d2e1f0",
      "workspace_lrn": "lrn:cloud:workspace:abcdef0123456789abcdef0123456789",
      "client_ip": "203.0.113.42",
      "client_user_agent": "curl/8.5.0",
      "surface": "console",
      "result": {
        "status": "success",
        "status_code": 200
      },
      "additional_details": {
        "api_key_lrn": "lrn:cloud:api_key:ffeeddccbbaa99887766554433221100"
      }
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Filesystems

List filesystems (deprecated path)

GET /api/v1/file-systems

Retrieves a list of your filesystems.

This path is deprecated in favor of GET /api/v1/filesystems, which is the spelling every other filesystem operation uses. The two return identical responses. This path is not scheduled for removal, so existing integrations keep working, but new ones should use /api/v1/filesystems.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Filesystem required
    • Filesystem

      Information about a shared filesystem.

      • id string required

        The unique identifier (ID) of the filesystem.

      • name string required

        The name of the filesystem.

      • mount_point string required

        The DEFAULT absolute path indicating where on instances the filesystem will be mounted. If file_system_mounts were used at launch time, the actual mount point is in the instance response.

      • created string required

        The date and time at which the filesystem was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • created_by User required

        The user in your Team that created the filesystem.

        • id string required

          The unique identifier for the user.

        • email string required

          The email address of the user.

        • status enum required

          The status of the user's account.

          • Possible values:
            • "active"
            • "deactivated"
      • is_in_use boolean required

        Whether the filesystem is currently mounted to an instance. Filesystems that are mounted cannot be deleted.

      • region Region required

        The region in which the filesystem is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • bytes_used integer optional

        The approximate amount of storage used by the filesystem in bytes. This estimate is updated every few hours.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/file-systems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "398578a2336b49079e74043f0bd2cfe8",
      "name": "my-filesystem",
      "mount_point": "/lambda/nfs/my-filesystem",
      "created": "1970-01-01T00:00:00.000Z",
      "created_by": {
        "id": "3da5a70a57a7422ea8a7203f98b2198b",
        "email": "me@example.com",
        "status": "active"
      },
      "is_in_use": false,
      "region": {
        "name": "string",
        "description": "string"
      },
      "bytes_used": 0
    }
  ]
}
Live
Send a request to see the response.

List filesystems

GET /api/v1/filesystems

Retrieves a list of your filesystems.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Filesystem required
    • Filesystem

      Information about a shared filesystem.

      • id string required

        The unique identifier (ID) of the filesystem.

      • name string required

        The name of the filesystem.

      • mount_point string required

        The DEFAULT absolute path indicating where on instances the filesystem will be mounted. If file_system_mounts were used at launch time, the actual mount point is in the instance response.

      • created string required

        The date and time at which the filesystem was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • created_by User required

        The user in your Team that created the filesystem.

        • id string required

          The unique identifier for the user.

        • email string required

          The email address of the user.

        • status enum required

          The status of the user's account.

          • Possible values:
            • "active"
            • "deactivated"
      • is_in_use boolean required

        Whether the filesystem is currently mounted to an instance. Filesystems that are mounted cannot be deleted.

      • region Region required

        The region in which the filesystem is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • bytes_used integer optional

        The approximate amount of storage used by the filesystem in bytes. This estimate is updated every few hours.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/filesystems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "398578a2336b49079e74043f0bd2cfe8",
      "name": "my-filesystem",
      "mount_point": "/lambda/nfs/my-filesystem",
      "created": "1970-01-01T00:00:00.000Z",
      "created_by": {
        "id": "3da5a70a57a7422ea8a7203f98b2198b",
        "email": "me@example.com",
        "status": "active"
      },
      "is_in_use": false,
      "region": {
        "name": "string",
        "description": "string"
      },
      "bytes_used": 0
    }
  ]
}
Live
Send a request to see the response.

Create filesystem

POST /api/v1/filesystems

Creates a new filesystem.

Body Parameters

  • name string required

    The name of the filesystem.

    • Minimum length: 1
    • Maximum length: 60
    • Regex pattern: ^[a-zA-Z]+[0-9a-zA-Z-]*$
  • region string required

    The region in which you want to create the filesystem.

Response:200

  • data Filesystem required

    Information about a shared filesystem.

    • id string required

      The unique identifier (ID) of the filesystem.

    • name string required

      The name of the filesystem.

    • mount_point string required

      The DEFAULT absolute path indicating where on instances the filesystem will be mounted. If file_system_mounts were used at launch time, the actual mount point is in the instance response.

    • created string required

      The date and time at which the filesystem was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • created_by User required

      The user in your Team that created the filesystem.

      • id string required

        The unique identifier for the user.

      • email string required

        The email address of the user.

      • status enum required

        The status of the user's account.

        • Possible values:
          • "active"
          • "deactivated"
    • is_in_use boolean required

      Whether the filesystem is currently mounted to an instance. Filesystems that are mounted cannot be deleted.

    • region Region required

      The region in which the filesystem is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • bytes_used integer optional

      The approximate amount of storage used by the filesystem in bytes. This estimate is updated every few hours.

Common Error Response Codes

400: Bad Request
  • "global/duplicate"
  • "global/quota-exceeded"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/invalid-address"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/filesystems' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "my-filesystem",
  "region": "us-west-1"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "398578a2336b49079e74043f0bd2cfe8",
    "name": "my-filesystem",
    "mount_point": "/lambda/nfs/my-filesystem",
    "created": "1970-01-01T00:00:00.000Z",
    "created_by": {
      "id": "3da5a70a57a7422ea8a7203f98b2198b",
      "email": "me@example.com",
      "status": "active"
    },
    "is_in_use": false,
    "region": {
      "name": "string",
      "description": "string"
    },
    "bytes_used": 0
  }
}
Live
Send a request to see the response.

Delete filesystem

DELETE /api/v1/filesystems/{id}

Deletes the filesystem with the specified ID. The filesystem must not be mounted to any running instances at the time of deletion.

Path Parameters

  • id string required

    The unique identifier (ID) of the filesystem to delete

Response:200

  • data FilesystemDeleteResponse required
    • deleted_ids array of string required

      The unique identifiers of the filesystems that were deleted.

      • string

Common Error Response Codes

400: Bad Request
  • "filesystems/filesystem-in-use"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/filesystems/398578a2336b49079e74043f0bd2cfe8' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "deleted_ids": [
      "398578a2336b49079e74043f0bd2cfe8"
    ]
  }
}
Live
Send a request to see the response.

Firewalls

List inbound firewall rules

GET /api/v1/firewall-rules

Retrieves a list of your firewall rules.

Note: Firewall rules do not apply to the us-south-1 region.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of FirewallRule required
    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rules' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}
Live
Send a request to see the response.

Replace inbound firewall rules

PUT /api/v1/firewall-rules

Overwrites the inbound firewall rules currently active for your account's instances with the desired rules.

Note: Firewall rules do not apply to the us-south-1 region.

Body Parameters

  • data array of FirewallRule required

    The list of inbound firewall rules.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data array of FirewallRule required
    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PUT --url 'https://cloud.lambda.ai/api/v1/firewall-rules' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "data": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}
Live
Send a request to see the response.

List firewall rulesets

GET /api/v1/firewall-rulesets

Retrieves a list of your firewall rulesets.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of FirewallRuleset required
    • FirewallRuleset

      A collection of firewall rules that can be associated with instances.

      • id string required

        The unique identifier of the firewall ruleset.

      • name string required

        The name of the firewall ruleset.

      • region Region required

        The region in which the firewall ruleset is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • rules array of FirewallRule required

        The list of firewall rules in this ruleset.

        • FirewallRule
          • protocol enum required

            The protocol to which the rule applies.

            • Possible values:
              • "tcp"
              • "udp"
              • "icmp"
              • "all"
          • port_range array of integer optional

            An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

            To specify a single port, list it twice (for example, [22,22]).

            • Minimum items: 2
            • Maximum items: 2
            • integer
              • Minimum : 1
              • Maximum : 65535
          • source_network string required

            The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

            This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

            • Format: ipv4network
          • description string required

            A human-readable description of the rule.

            • Minimum length: 0
            • Maximum length: 128
      • created string required

        The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • instance_ids array of string required

        The IDs of instances this firewall ruleset is associated with.

        • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "c4d291f47f9d436fa39f58493ce3b50d",
      "name": "My Firewall Ruleset",
      "region": {
        "name": "string",
        "description": "string"
      },
      "rules": [
        {
          "protocol": "tcp",
          "port_range": [
            22,
            22
          ],
          "source_network": "0.0.0.0/0",
          "description": "Allow SSH from anywhere"
        }
      ],
      "created": "1970-01-01T00:00:00.000Z",
      "instance_ids": [
        "string"
      ]
    }
  ]
}
Live
Send a request to see the response.

Create firewall ruleset

POST /api/v1/firewall-rulesets

Creates a new firewall ruleset with the specified name and rules.

Body Parameters

  • name string required

    The name of the firewall ruleset.

    • Maximum length: 64
  • region string required

    The region in which the firewall ruleset is deployed.

  • rules array of FirewallRule required

    The firewall rules to include in the ruleset.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data FirewallRuleset required

    A collection of firewall rules that can be associated with instances.

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

          To specify a single port, list it twice (for example, [22,22]).

          • Minimum items: 2
          • Maximum items: 2
          • integer
            • Minimum : 1
            • Maximum : 65535
        • source_network string required

          The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

          This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

          • Format: ipv4network
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

      The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/quota-exceeded"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Firewall Ruleset",
  "region": "string",
  "rules": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Firewall Ruleset",
    "region": {
      "name": "string",
      "description": "string"
    },
    "rules": [
      {
        "protocol": "tcp",
        "port_range": [
          22,
          22
        ],
        "source_network": "0.0.0.0/0",
        "description": "Allow SSH from anywhere"
      }
    ],
    "created": "1970-01-01T00:00:00.000Z",
    "instance_ids": [
      "string"
    ]
  }
}
Live
Send a request to see the response.

Retrieve global firewall ruleset details

GET /api/v1/firewall-rulesets/global

Retrieves the details of the global firewall ruleset.

Parameters

There are no parameters for this endpoint.

Response:200

  • data GlobalFirewallRuleset required

    Firewall rules that apply across all regions.

    • id string required

      The unique identifier of the firewall ruleset.

      • Const: "global"
    • name string required

      The name of the firewall ruleset.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

          To specify a single port, list it twice (for example, [22,22]).

          • Minimum items: 2
          • Maximum items: 2
          • integer
            • Minimum : 1
            • Maximum : 65535
        • source_network string required

          The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

          This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

          • Format: ipv4network
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/global' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "global",
    "name": "Default Workspace Global Rules",
    "rules": [
      {
        "protocol": "tcp",
        "port_range": [
          22,
          22
        ],
        "source_network": "0.0.0.0/0",
        "description": "Allow SSH from anywhere"
      }
    ]
  }
}
Live
Send a request to see the response.

Update global firewall ruleset

PATCH /api/v1/firewall-rulesets/global

Updates the global firewall ruleset. This allows updating the rules only.

Body Parameters

  • rules array of FirewallRule optional

    The new firewall rules for the ruleset. If not provided, the rules will not be updated.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data GlobalFirewallRuleset required

    Firewall rules that apply across all regions.

    • id string required

      The unique identifier of the firewall ruleset.

      • Const: "global"
    • name string required

      The name of the firewall ruleset.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

          To specify a single port, list it twice (for example, [22,22]).

          • Minimum items: 2
          • Maximum items: 2
          • integer
            • Minimum : 1
            • Maximum : 65535
        • source_network string required

          The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

          This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

          • Format: ipv4network
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/global' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "rules": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "global",
    "name": "Default Workspace Global Rules",
    "rules": [
      {
        "protocol": "tcp",
        "port_range": [
          22,
          22
        ],
        "source_network": "0.0.0.0/0",
        "description": "Allow SSH from anywhere"
      }
    ]
  }
}
Live
Send a request to see the response.

Retrieve firewall ruleset details

GET /api/v1/firewall-rulesets/{id}

Retrieves the details of a specific firewall ruleset.

Path Parameters

  • id string required

    The unique identifier (ID) of the firewall ruleset

Response:200

  • data FirewallRuleset required

    A collection of firewall rules that can be associated with instances.

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

          To specify a single port, list it twice (for example, [22,22]).

          • Minimum items: 2
          • Maximum items: 2
          • integer
            • Minimum : 1
            • Maximum : 65535
        • source_network string required

          The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

          This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

          • Format: ipv4network
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

      The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Firewall Ruleset",
    "region": {
      "name": "string",
      "description": "string"
    },
    "rules": [
      {
        "protocol": "tcp",
        "port_range": [
          22,
          22
        ],
        "source_network": "0.0.0.0/0",
        "description": "Allow SSH from anywhere"
      }
    ],
    "created": "1970-01-01T00:00:00.000Z",
    "instance_ids": [
      "string"
    ]
  }
}
Live
Send a request to see the response.

Update firewall ruleset

PATCH /api/v1/firewall-rulesets/{id}

Updates a firewall ruleset. This is a partial update that allows updating either the name, rules, or both.

Path Parameters

  • id string required

    The unique identifier (ID) of the firewall ruleset

Body Parameters

  • name string optional

    The new name for the firewall ruleset. If not provided, the name will not be updated.

    • Maximum length: 64
  • rules array of FirewallRule optional

    The new firewall rules for the ruleset. If not provided, the rules will not be updated.

    • FirewallRule
      • protocol enum required

        The protocol to which the rule applies.

        • Possible values:
          • "tcp"
          • "udp"
          • "icmp"
          • "all"
      • port_range array of integer optional

        An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

        To specify a single port, list it twice (for example, [22,22]).

        • Minimum items: 2
        • Maximum items: 2
        • integer
          • Minimum : 1
          • Maximum : 65535
      • source_network string required

        The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

        This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

        • Format: ipv4network
      • description string required

        A human-readable description of the rule.

        • Minimum length: 0
        • Maximum length: 128

Response:200

  • data FirewallRuleset required

    A collection of firewall rules that can be associated with instances.

    • id string required

      The unique identifier of the firewall ruleset.

    • name string required

      The name of the firewall ruleset.

    • region Region required

      The region in which the firewall ruleset is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • rules array of FirewallRule required

      The list of firewall rules in this ruleset.

      • FirewallRule
        • protocol enum required

          The protocol to which the rule applies.

          • Possible values:
            • "tcp"
            • "udp"
            • "icmp"
            • "all"
        • port_range array of integer optional

          An inclusive range of network ports specified as [min, max]. Not allowed for the icmp protocol but required for the others.

          To specify a single port, list it twice (for example, [22,22]).

          • Minimum items: 2
          • Maximum items: 2
          • integer
            • Minimum : 1
            • Maximum : 65535
        • source_network string required

          The set of source IPv4 addresses from which you want to allow inbound traffic. These addresses must be specified in CIDR notation. You can specify individual public IPv4 CIDR blocks such as 1.2.3.4 or 1.2.3.4/32, or you can specify 0.0.0.0/0 to allow access from any address.

          This value is a string consisting of a public IPv4 address optionally followed by a slash (/) and an integer mask (the network prefix). If no mask is provided, the API assumes /32 by default.

          • Format: ipv4network
        • description string required

          A human-readable description of the rule.

          • Minimum length: 0
          • Maximum length: 128
    • created string required

      The date and time at which the firewall ruleset was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • instance_ids array of string required

      The IDs of instances this firewall ruleset is associated with.

      • string

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Updated Firewall Ruleset",
  "rules": [
    {
      "protocol": "tcp",
      "port_range": [
        22,
        22
      ],
      "source_network": "0.0.0.0/0",
      "description": "Allow SSH from anywhere"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Firewall Ruleset",
    "region": {
      "name": "string",
      "description": "string"
    },
    "rules": [
      {
        "protocol": "tcp",
        "port_range": [
          22,
          22
        ],
        "source_network": "0.0.0.0/0",
        "description": "Allow SSH from anywhere"
      }
    ],
    "created": "1970-01-01T00:00:00.000Z",
    "instance_ids": [
      "string"
    ]
  }
}
Live
Send a request to see the response.

Delete firewall ruleset

DELETE /api/v1/firewall-rulesets/{id}

Deletes the firewall ruleset with the specified ID.

Path Parameters

  • id string required

    The unique identifier (ID) of the firewall ruleset

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "firewall-rulesets/firewall-ruleset-in-use"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/internal-error"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/firewall-rulesets/c4d291f47f9d436fa39f58493ce3b50d' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

Groups

Groups of identities, their memberships, and the roles and workspaces assigned to them.

List groups

GET /api/v1/groups

Lists all groups in the account.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

Response:200

  • data array of Group required
    • Group
      • id string required

        The unique identifier (ID) of the group.

      • account_id string required

        The ID of the account that the group belongs to.

      • name string required

        The name of the group.

      • description (string | null) required

        The description of the group.

        Any of
        • string
        • null
  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "account_id": "ddaedf1b7a0e41ac981711504493b242",
      "name": "string",
      "description": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Create a new group

POST /api/v1/groups

Creates a new group.

Body Parameters

  • name string required

    The name of the group.

  • description (string | null) optional

    The description of the group.

    Any of
    • string
    • null

Response:200

  • data Group required
    • id string required

      The unique identifier (ID) of the group.

    • account_id string required

      The ID of the account that the group belongs to.

    • name string required

      The name of the group.

    • description (string | null) required

      The description of the group.

      Any of
      • string
      • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/groups' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "string",
  "description": "string"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "name": "string",
    "description": "string"
  }
}
Live
Send a request to see the response.

Retrieve a group's details

GET /api/v1/groups/{group_id}

Retrieves details for the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Response:200

  • data Group required
    • id string required

      The unique identifier (ID) of the group.

    • account_id string required

      The ID of the account that the group belongs to.

    • name string required

      The name of the group.

    • description (string | null) required

      The description of the group.

      Any of
      • string
      • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "name": "string",
    "description": "string"
  }
}
Live
Send a request to see the response.

Update a group's details

PATCH /api/v1/groups/{group_id}

Updates details for the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Body Parameters

  • name string optional

    The name of the group.

  • description (string | null) optional

    The description of the group.

    Any of
    • string
    • null

Response:200

  • data Group required
    • id string required

      The unique identifier (ID) of the group.

    • account_id string required

      The ID of the account that the group belongs to.

    • name string required

      The name of the group.

    • description (string | null) required

      The description of the group.

      Any of
      • string
      • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "string",
  "description": "string"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "name": "string",
    "description": "string"
  }
}
Live
Send a request to see the response.

Delete a group

DELETE /api/v1/groups/{group_id}

Deletes the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List the members of a group

GET /api/v1/groups/{group_id}/memberships

Lists the members of the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • search string optional

    Case-insensitive substring filter on the member's name or email.

    • Maximum length: 128
  • identity_type enum optional

    Filter memberships by the member's identity type. If omitted, all members are returned.

    • Possible values:
      • "user"
      • "service"

Response:200

  • data array of GroupMembership required
    • GroupMembership
      • id string required

        The unique identifier (ID) of the group membership.

      • group_id string required

        The unique identifier (ID) of the group.

      • member_id string required

        The unique identifier (ID) of the identity that is a member of the group.

      • member_type string required

        The member's type.

        • Const: "identity"
  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/memberships' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "group_id": "ddaedf1b7a0e41ac981711504493b242",
      "member_id": "ddaedf1b7a0e41ac981711504493b242",
      "member_type": "identity"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Add a member to a group

POST /api/v1/groups/{group_id}/memberships

Adds the specified identity to the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Body Parameters

  • member_id string required

    The unique identifier (ID) of the identity to add to the group.

  • member_type string optional

    The member's type.

    • Const: "identity"

Response:200

  • data GroupMembership required
    • id string required

      The unique identifier (ID) of the group membership.

    • group_id string required

      The unique identifier (ID) of the group.

    • member_id string required

      The unique identifier (ID) of the identity that is a member of the group.

    • member_type string required

      The member's type.

      • Const: "identity"

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/memberships' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "member_id": "ddaedf1b7a0e41ac981711504493b242",
  "member_type": "identity"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "group_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_type": "identity"
  }
}
Live
Send a request to see the response.

Retrieve a member's details

GET /api/v1/groups/{group_id}/memberships/{membership_id}

Retrieves a group member's membership details.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

  • membership_id string required

    The unique identifier (ID) of the group membership.

Response:200

  • data GroupMembership required
    • id string required

      The unique identifier (ID) of the group membership.

    • group_id string required

      The unique identifier (ID) of the group.

    • member_id string required

      The unique identifier (ID) of the identity that is a member of the group.

    • member_type string required

      The member's type.

      • Const: "identity"

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/memberships/8ce75d9f9b9a508495c5fec565fd5304' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "group_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_type": "identity"
  }
}
Live
Send a request to see the response.

Remove a member from a group

DELETE /api/v1/groups/{group_id}/memberships/{membership_id}

Revokes an identity's membership in the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

  • membership_id string required

    The unique identifier (ID) of the group membership.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/memberships/8ce75d9f9b9a508495c5fec565fd5304' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List a group's role assignments

GET /api/v1/groups/{group_id}/role-assignments

Lists all roles assigned to the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • scope enum optional

    The role scope to filter the results by. If omitted, all role scopes are returned.

    • Possible values:
      • "account"
      • "workspace"
  • workspace_id string optional

    The workspace to filter the results by. Required if scope is set to workspace.

Response:200

  • data array of RoleBackedRoleAssignment required
    • RoleBackedRoleAssignment

      A role assignment that grants a role.

      • id string required

        The unique identifier (ID) of the role assignment.

      • scope (AccountRoleScope | WorkspaceRoleScope) required

        The scope at which the assignment applies.

        Any of
        • AccountRoleScope
          • type string required

            Account-wide scope.

            • Const: "account"
        • WorkspaceRoleScope
          • type string required

            Workspace scope.

            • Const: "workspace"
          • workspace_id string required

            The workspace the assignment applies to.

      • source RoleAssignmentSource optional

        The source of the role assignment. Appears only when the role assignment is inherited from a group.

        • via_group_id string required

          The group whose membership grants this inherited assignment.

      • role_assignment_type string required

        The role assignment's type.

        • Const: "role"
      • role_id string required

        The unique identifier (ID) of the role.

      • role_name string required

        The name of the role.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/role-assignments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "scope": {
        "type": "account"
      },
      "source": {
        "via_group_id": "ddaedf1b7a0e41ac981711504493b242"
      },
      "role_assignment_type": "role",
      "role_id": "ddaedf1b7a0e41ac981711504493b242",
      "role_name": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Assign a role to a group

POST /api/v1/groups/{group_id}/role-assignments

Assigns the specified role to the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Body Parameters

  • role_assignment_type string optional

    The type of role assignment to create. Defaults to role.

    • Const: "role"
  • role_id string required

    The unique identifier (ID) of the role.

  • scope (AccountRoleScope | WorkspaceRoleScope) required

    The scope at which to assign the role.

    Any of
    • AccountRoleScope
      • type string required

        Account-wide scope.

        • Const: "account"
    • WorkspaceRoleScope
      • type string required

        Workspace scope.

        • Const: "workspace"
      • workspace_id string required

        The workspace the assignment applies to.

Response:200

  • data RoleBackedRoleAssignment required

    A role assignment that grants a role.

    • id string required

      The unique identifier (ID) of the role assignment.

    • scope (AccountRoleScope | WorkspaceRoleScope) required

      The scope at which the assignment applies.

      Any of
      • AccountRoleScope
        • type string required

          Account-wide scope.

          • Const: "account"
      • WorkspaceRoleScope
        • type string required

          Workspace scope.

          • Const: "workspace"
        • workspace_id string required

          The workspace the assignment applies to.

    • source RoleAssignmentSource optional

      The source of the role assignment. Appears only when the role assignment is inherited from a group.

      • via_group_id string required

        The group whose membership grants this inherited assignment.

    • role_assignment_type string required

      The role assignment's type.

      • Const: "role"
    • role_id string required

      The unique identifier (ID) of the role.

    • role_name string required

      The name of the role.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/role-assignments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "role_assignment_type": "role",
  "role_id": "ddaedf1b7a0e41ac981711504493b242",
  "scope": {
    "type": "account"
  }
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "scope": {
      "type": "account"
    },
    "source": {
      "via_group_id": "ddaedf1b7a0e41ac981711504493b242"
    },
    "role_assignment_type": "role",
    "role_id": "ddaedf1b7a0e41ac981711504493b242",
    "role_name": "string"
  }
}
Live
Send a request to see the response.

Unassign a role from a group

DELETE /api/v1/groups/{group_id}/role-assignments/{assignment_id}

Revokes the specified role assignment from the specified group.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

  • assignment_id string required

    The unique identifier (ID) of the role assignment.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/groups/7bd64c8f8a89497384b4deb454fc4293/role-assignments/9f6e4b2a7c1d3f8e05124a9b6c3d8e01' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List a group's workspaces

GET /api/v1/groups/{group_id}/workspaces

Lists the workspaces the specified group can access.

Path Parameters

  • group_id string required

    The unique identifier (ID) of the group.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

Response:200

  • data array of Workspace required
    • Workspace

      A workspace provides logical isolation for resources within an account.

      • id string required

        The unique identifier (ID) of the workspace.

      • name string required

        The name of the workspace.

      • account_id string required

        The unique identifier of the account that owns this workspace.

      • created string required

        The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • is_default boolean required

        Whether this is the default workspace for the account.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/groups/ddaedf1b7a0e41ac981711504493b242/workspaces' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "c4d291f47f9d436fa39f58493ce3b50d",
      "name": "My Workspace",
      "account_id": "a8d9c6729e12468786d1c44c0e942719",
      "created": "1970-01-01T00:00:00.000Z",
      "is_default": false
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Identities

Users and service identities in an account, and what each one holds: API keys, group memberships, role assignments, and workspaces.

List identities

GET /api/v1/identities

Lists the identities in the account the requesting identity belongs to.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • identity_type enum optional

    The type of identity to filter the results by. If omitted, all identity types are returned.

    • Possible values:
      • "user"
      • "service"
  • search string optional

    A list of search tokens, separated by + or %20. Iteratively filters against each successive token in the list (AND behavior). For user identities, searches the first name, last name, and email for the token. For service identities, searches the display name. Requires identity_type to be set.

    • Maximum length: 128

Response:200

  • data array of (UserIdentity | ServiceIdentity) required
    • (UserIdentity | ServiceIdentity)
      Any of
      • UserIdentity
        • id string required

          The unique identifier (ID) of the identity.

        • account_id string required

          The ID of the account that the identity belongs to.

        • identity_type string required

          The type of the identity.

          • Const: "user"
        • created_at string optional

          The time the identity was created.

          • Format: date-time
        • email string required

          The email address of the user.

        • is_verified boolean required

          Whether the user's email address has been verified.

        • first_name string optional

          The first name of the user.

        • last_name string optional

          The last name of the user.

      • ServiceIdentity
        • id string required

          The unique identifier (ID) of the identity.

        • account_id string required

          The ID of the account that the identity belongs to.

        • identity_type string required

          The type of the identity.

          • Const: "service"
        • created_at string optional

          The time the identity was created.

          • Format: date-time
        • display_name string required

          The display name of the service identity.

        • is_managed boolean required

          Whether this service identity is managed by Lambda.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "account_id": "ddaedf1b7a0e41ac981711504493b242",
      "identity_type": "user",
      "created_at": "1970-01-01T00:00:00.000Z",
      "email": "string",
      "is_verified": false,
      "first_name": "string",
      "last_name": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Create an identity

POST /api/v1/identities

Creates a new identity in the same account as the identity that sent the API request. Creating a user identity requires an SSO-enabled account.

Body Parameters

(CreateServiceIdentityRequest | CreateUserIdentityRequest) required
Any of
  • CreateServiceIdentityRequest
    • identity_type string optional

      The type of identity to create. Defaults to service.

      • Const: "service"
    • display_name string required

      A user-provided name for the identity.

      • Minimum length: 1
      • Maximum length: 150
    • role_ids array of string optional

      The IDs of the account roles to assign to the new identity. To view a list of account roles and their role IDs, call List roles and filter by role_type.

      • string
  • CreateUserIdentityRequest
    • identity_type string required

      The type of identity to create.

      • Const: "user"
    • email string required

      Email address for the identity. Must not be in use by another identity.

      • Format: email
    • first_name string optional

      The first name of the user.

    • last_name string optional

      The last name of the user.

    • role_ids array of string optional

      The IDs of the account roles to assign to the new identity. To view a list of account roles and their role IDs, call List roles and filter by role_type. When omitted, the identity receives the default account-member role.

      • string

Response:201

  • data (ServiceIdentity | UserIdentity) required
    Any of
    • ServiceIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "service"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • display_name string required

        The display name of the service identity.

      • is_managed boolean required

        Whether this service identity is managed by Lambda.

    • UserIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "user"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • email string required

        The email address of the user.

      • is_verified boolean required

        Whether the user's email address has been verified.

      • first_name string optional

        The first name of the user.

      • last_name string optional

        The last name of the user.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/identities' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "identity_type": "service",
  "display_name": "a",
  "role_ids": [
    "ddaedf1b7a0e41ac981711504493b242"
  ]
}'
Response
Sample

ResponseStatus: 201 Created

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "identity_type": "service",
    "created_at": "1970-01-01T00:00:00.000Z",
    "display_name": "string",
    "is_managed": false
  }
}
Live
Send a request to see the response.

Retrieve identity details

GET /api/v1/identities/{identity_id}

Retrieves metadata for the specified identity, if it exists.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Response:200

  • data (UserIdentity | ServiceIdentity) required
    Any of
    • UserIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "user"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • email string required

        The email address of the user.

      • is_verified boolean required

        Whether the user's email address has been verified.

      • first_name string optional

        The first name of the user.

      • last_name string optional

        The last name of the user.

    • ServiceIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "service"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • display_name string required

        The display name of the service identity.

      • is_managed boolean required

        Whether this service identity is managed by Lambda.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities/7bd64c8f8a89497384b4deb454fc4293' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "identity_type": "user",
    "created_at": "1970-01-01T00:00:00.000Z",
    "email": "string",
    "is_verified": false,
    "first_name": "string",
    "last_name": "string"
  }
}
Live
Send a request to see the response.

Update an identity's name

PATCH /api/v1/identities/{identity_id}

Updates the name of the specified identity.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Body Parameters

  • display_name string required
    • Minimum length: 1
    • Maximum length: 150

Response:200

  • data ServiceIdentity required
    • id string required

      The unique identifier (ID) of the identity.

    • account_id string required

      The ID of the account that the identity belongs to.

    • identity_type string required

      The type of the identity.

      • Const: "service"
    • created_at string optional

      The time the identity was created.

      • Format: date-time
    • display_name string required

      The display name of the service identity.

    • is_managed boolean required

      Whether this service identity is managed by Lambda.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "display_name": "a"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "identity_type": "service",
    "created_at": "1970-01-01T00:00:00.000Z",
    "display_name": "string",
    "is_managed": false
  }
}
Live
Send a request to see the response.

Delete an identity

DELETE /api/v1/identities/{identity_id}

Deletes the specified identity from the account. Returns an error if you attempt to delete your own identity, if the identity you tried to delete is the only remaining admin in the account, or if the identity is Lambda-managed.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List an identity's API keys

GET /api/v1/identities/{identity_id}/api-keys

Lists the API keys associated with the specified identity. To list API keys associated with identities other than you own, you must have a role that contains the relevant permissions.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • status enum optional

    The API key status to filter the API keys by. If omitted, all API key statuses are returned.

    • Possible values:
      • "active"
      • "expired"

Response:200

  • data array of ApiKeyResponse required
    • ApiKeyResponse
      • id string required

        The unique identifier (ID) of the API key.

      • name string required

        The user-defined name of the API key.

      • identity_id string required

        The unique identifier (ID) of the identity that owns the API key.

      • created_at string required

        The date and time at which the API key was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • expires_at (string | null) required

        The date and time at which the API key will expire. Formatted as an ISO 8601 timestamp. Returns null if no expiration period was set during key creation.

        Any of
        • string
          • Format: date-time
        • null
      • last_used_at (string | null) required

        The date and time at which the API key was last used. Formatted as an ISO 8601 timestamp. Returns null if the key hasn't been used.

        Any of
        • string
          • Format: date-time
        • null
      • status enum required

        The current status of the API key.

        • Possible values:
          • "active"
          • "expired"
      • identity_type enum optional

        Whether the owning identity is a user or a service identity.

        • Possible values:
          • "user"
          • "service"
      • identity_display_name string optional

        The owning identity's display name: a user's full name or a service identity's name. Empty when the identity has no name on record.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242/api-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "identity_id": "ddaedf1b7a0e41ac981711504493b242",
      "created_at": "1970-01-01T00:00:00.000Z",
      "expires_at": "1970-01-01T00:00:00.000Z",
      "last_used_at": "1970-01-01T00:00:00.000Z",
      "status": "active",
      "identity_type": "user",
      "identity_display_name": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Create an API key for an identity

POST /api/v1/identities/{identity_id}/api-keys

Creates an API key for the specified identity. To list API keys associated with identities other than your own, you must have a role that contains the relevant permissions.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Body Parameters

  • name string required
    • Minimum length: 1
    • Maximum length: 64
    • Regex pattern: ^[0-9a-zA-Z][0-9a-zA-Z -]*$
  • expires_in integer optional

    The API key lifetime in seconds. If omitted, the API key does not expire. Expired keys remain listed but do not count toward the service identity's active API key limit.

Response:201

  • data ApiKeyCreatedResponse required
    • id string required

      The unique identifier (ID) of the API key.

    • name string required

      The user-defined name of the API key.

    • identity_id string required

      The unique identifier (ID) of the identity that owns the API key.

    • created_at string required

      The date and time at which the API key was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • expires_at (string | null) required

      The date and time at which the API key will expire. Formatted as an ISO 8601 timestamp. Returns null if no expiration period was set during key creation.

      Any of
      • string
        • Format: date-time
      • null
    • last_used_at (string | null) required

      The date and time at which the API key was last used. Formatted as an ISO 8601 timestamp. Returns null if the key hasn't been used.

      Any of
      • string
        • Format: date-time
      • null
    • status enum required

      The current status of the API key.

      • Possible values:
        • "active"
        • "expired"
    • identity_type enum optional

      Whether the owning identity is a user or a service identity.

      • Possible values:
        • "user"
        • "service"
    • identity_display_name string optional

      The owning identity's display name: a user's full name or a service identity's name. Empty when the identity has no name on record.

    • api_key string required

      The newly created API key.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242/api-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "my-api-key",
  "expires_in": 3600
}'
Response
Sample

ResponseStatus: 201 Created

{
  "data": {
    "id": "string",
    "name": "string",
    "identity_id": "ddaedf1b7a0e41ac981711504493b242",
    "created_at": "1970-01-01T00:00:00.000Z",
    "expires_at": "1970-01-01T00:00:00.000Z",
    "last_used_at": "1970-01-01T00:00:00.000Z",
    "status": "active",
    "identity_type": "user",
    "identity_display_name": "string",
    "api_key": "string"
  }
}
Live
Send a request to see the response.

List an identity's group memberships

GET /api/v1/identities/{identity_id}/groups

Lists the groups the specified identity belongs to.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • search string optional

    A user-provided string to filter the results by.

    • Maximum length: 128

Response:200

  • data array of IdentityGroup required
    • IdentityGroup

      A group an identity belongs to. Dashboard-only.

      Carries the membership id so the caller can remove the identity from the group without a second lookup: the delete route is addressed by membership, not by (group, identity).

      • id string required

        The unique identifier (ID) of the group.

      • account_id string required

        The ID of the account that the group belongs to.

      • name string required

        The name of the group.

      • description (string | null) required

        The description of the group.

        Any of
        • string
        • null
      • membership_id string required

        The unique identifier (ID) of the membership linking the identity to this group.

      • membership_created_at string optional

        The date and time at which the identity joined the group. Formatted as an ISO 8601 timestamp.

        • Format: date-time
  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242/groups' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "account_id": "ddaedf1b7a0e41ac981711504493b242",
      "name": "string",
      "description": "string",
      "membership_id": "ddaedf1b7a0e41ac981711504493b242",
      "membership_created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

List an identity's role assignments

GET /api/v1/identities/{identity_id}/role-assignments

Lists the roles assigned to the specified identity, including roles assigned to groups the identity is a member of.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • scope enum optional

    The role scope to filter the results by. If omitted, all role scopes are returned.

    • Possible values:
      • "account"
      • "workspace"
  • workspace_id string optional

    The workspace to filter the results by. Required if scope is set to workspace.

  • include_inherited boolean optional

    If set, results will include role assignments inherited from the groups the identity belongs to.

  • source enum optional

    The source to filter the results by. direct returns the identity's direct role assignments, and group returns role assignments the identity inherits from the groups it belongs to. If omitted, all role assignments are returned.

    • Possible values:
      • "direct"
      • "group"
  • source_group_id string optional

    If set, limits results to role assignments inherited by the specified group.

  • search string optional

    A user-provided string to filter the results by.

    • Maximum length: 128

Response:200

  • data array of RoleBackedRoleAssignment required
    • RoleBackedRoleAssignment

      A role assignment that grants a role.

      • id string required

        The unique identifier (ID) of the role assignment.

      • scope (AccountRoleScope | WorkspaceRoleScope) required

        The scope at which the assignment applies.

        Any of
        • AccountRoleScope
          • type string required

            Account-wide scope.

            • Const: "account"
        • WorkspaceRoleScope
          • type string required

            Workspace scope.

            • Const: "workspace"
          • workspace_id string required

            The workspace the assignment applies to.

      • source RoleAssignmentSource optional

        The source of the role assignment. Appears only when the role assignment is inherited from a group.

        • via_group_id string required

          The group whose membership grants this inherited assignment.

      • role_assignment_type string required

        The role assignment's type.

        • Const: "role"
      • role_id string required

        The unique identifier (ID) of the role.

      • role_name string required

        The name of the role.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities/7bd64c8f8a89497384b4deb454fc4293/role-assignments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "scope": {
        "type": "account"
      },
      "source": {
        "via_group_id": "ddaedf1b7a0e41ac981711504493b242"
      },
      "role_assignment_type": "role",
      "role_id": "ddaedf1b7a0e41ac981711504493b242",
      "role_name": "string"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Assign a role to an identity

POST /api/v1/identities/{identity_id}/role-assignments

Assigns the specified role to the specified identity.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Body Parameters

  • role_assignment_type string optional

    The type of role assignment to create. Defaults to role.

    • Const: "role"
  • role_id string required

    The unique identifier (ID) of the role.

  • scope (AccountRoleScope | WorkspaceRoleScope) required

    The scope at which to assign the role.

    Any of
    • AccountRoleScope
      • type string required

        Account-wide scope.

        • Const: "account"
    • WorkspaceRoleScope
      • type string required

        Workspace scope.

        • Const: "workspace"
      • workspace_id string required

        The workspace the assignment applies to.

Response:200

  • data RoleBackedRoleAssignment required

    A role assignment that grants a role.

    • id string required

      The unique identifier (ID) of the role assignment.

    • scope (AccountRoleScope | WorkspaceRoleScope) required

      The scope at which the assignment applies.

      Any of
      • AccountRoleScope
        • type string required

          Account-wide scope.

          • Const: "account"
      • WorkspaceRoleScope
        • type string required

          Workspace scope.

          • Const: "workspace"
        • workspace_id string required

          The workspace the assignment applies to.

    • source RoleAssignmentSource optional

      The source of the role assignment. Appears only when the role assignment is inherited from a group.

      • via_group_id string required

        The group whose membership grants this inherited assignment.

    • role_assignment_type string required

      The role assignment's type.

      • Const: "role"
    • role_id string required

      The unique identifier (ID) of the role.

    • role_name string required

      The name of the role.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/identities/7bd64c8f8a89497384b4deb454fc4293/role-assignments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "role_assignment_type": "role",
  "role_id": "ddaedf1b7a0e41ac981711504493b242",
  "scope": {
    "type": "account"
  }
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "scope": {
      "type": "account"
    },
    "source": {
      "via_group_id": "ddaedf1b7a0e41ac981711504493b242"
    },
    "role_assignment_type": "role",
    "role_id": "ddaedf1b7a0e41ac981711504493b242",
    "role_name": "string"
  }
}
Live
Send a request to see the response.

Unassign a role from an identity

DELETE /api/v1/identities/{identity_id}/role-assignments/{assignment_id}

Revokes the specified role assignment from the specified identity.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

  • assignment_id string required

    The unique identifier (ID) of the role assignment.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/identities/7bd64c8f8a89497384b4deb454fc4293/role-assignments/9f6e4b2a7c1d3f8e05124a9b6c3d8e01' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List an identity's workspaces

GET /api/v1/identities/{identity_id}/workspaces

Lists the workspaces the specified identity can access.

Path Parameters

  • identity_id string required

    The unique identifier (ID) of the identity.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

Response:200

  • data array of Workspace required
    • Workspace

      A workspace provides logical isolation for resources within an account.

      • id string required

        The unique identifier (ID) of the workspace.

      • name string required

        The name of the workspace.

      • account_id string required

        The unique identifier of the account that owns this workspace.

      • created string required

        The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • is_default boolean required

        Whether this is the default workspace for the account.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identities/ddaedf1b7a0e41ac981711504493b242/workspaces' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "c4d291f47f9d436fa39f58493ce3b50d",
      "name": "My Workspace",
      "account_id": "a8d9c6729e12468786d1c44c0e942719",
      "created": "1970-01-01T00:00:00.000Z",
      "is_default": false
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Get current identity

GET /api/v1/identity

Retrieves the details of the current identity.

Parameters

There are no parameters for this endpoint.

Response:200

  • data (UserIdentity | ServiceIdentity) required
    Any of
    • UserIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "user"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • email string required

        The email address of the user.

      • is_verified boolean required

        Whether the user's email address has been verified.

      • first_name string optional

        The first name of the user.

      • last_name string optional

        The last name of the user.

    • ServiceIdentity
      • id string required

        The unique identifier (ID) of the identity.

      • account_id string required

        The ID of the account that the identity belongs to.

      • identity_type string required

        The type of the identity.

        • Const: "service"
      • created_at string optional

        The time the identity was created.

        • Format: date-time
      • display_name string required

        The display name of the service identity.

      • is_managed boolean required

        Whether this service identity is managed by Lambda.

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/identity' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "account_id": "ddaedf1b7a0e41ac981711504493b242",
    "identity_type": "user",
    "created_at": "1970-01-01T00:00:00.000Z",
    "email": "string",
    "is_verified": false,
    "first_name": "string",
    "last_name": "string"
  }
}
Live
Send a request to see the response.

Images

List available images

GET /api/v1/images

Retrieves a list of available images by region.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Image required
    • Image

      An available machine image in Lambda Cloud.

      • id string required

        The unique identifier (ID) for an image.

      • created_time string required

        The date and time that the image was created.

        • Format: date-time
      • updated_time string required

        The date and time that the image was last updated.

        • Format: date-time
      • name string required

        The human-readable identifier for an image.

      • description string required

        Additional information about the image.

      • family string required

        The family the image belongs to.

      • version string required

        The image version.

      • architecture enum required

        The CPU architecture the image supports.

        • Possible values:
          • "x86_64"
          • "arm64"
      • region Region required

        The region in which this image is available.

        • name string required

          The region code.

        • description string required

          The region description.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/images' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
      "created_time": "1970-01-01T00:00:00.000Z",
      "updated_time": "1970-01-01T00:00:00.000Z",
      "name": "ubuntu-24.04.01",
      "description": "Ubuntu LTS",
      "family": "ubuntu-lts",
      "version": "24.04.01",
      "architecture": "x86_64",
      "region": {
        "name": "string",
        "description": "string"
      }
    }
  ]
}
Live
Send a request to see the response.

Instances

Launch instances

POST /api/v1/instance-operations/launch

Launches a Lambda On-Demand Cloud instance.

Body Parameters

  • region_name string required

    The region into which you want to launch the instance.

  • instance_type_name string required

    The type of instance you want to launch. To retrieve a list of available instance types, see List available instance types.

  • ssh_key_names array of string required

    The names of the SSH keys you want to use to provide access to the instance. Currently, exactly one SSH key must be specified.

    • string
  • file_system_names array of string optional

    The names of the filesystems you want to mount to the instance. When specified alongside file_system_mounts, any filesystems referred to in both lists will use the mount path specified in file_system_mounts, rather than the default.

    • string
  • file_system_mounts array of RequestedFilesystemMountEntry optional

    The filesystem mounts to mount to the instance. When specified alongside file_system_names, any filesystems referred to in both lists will use the mount path specified in file_system_mounts, rather than the default.

    • RequestedFilesystemMountEntry

      The mount point for a filesystem mounted to an instance.

      • mount_point string required

        The absolute path indicating where on the instance the filesystem will be mounted.

        • Maximum length: 256
        • Regex pattern: ^(/home|/lambda/nfs|/data)[//a-zA-Z0-9-]*$
      • file_system_id string required

        The id of the filesystem to mount to the instance.

  • hostname string optional

    The hostname to assign to the instance. If not specified, a default, IP-address-based hostname is assigned. This hostname is driven into /etc/hostname on the instance.

    • Minimum length: 1
    • Maximum length: 63
    • Regex pattern: ^[a-z0-9][0-9a-z-]{0,62}$
  • name string optional

    The name you want to assign to your instance. Must be 64 characters or fewer.

    • Minimum length: 0
    • Maximum length: 64
  • image (ImageSpecificationID | ImageSpecificationFamily) optional

    The machine image you want to use. Defaults to the latest Lambda Stack image.

    Any of
    • ImageSpecificationID

      Specifies the image to use by its unique identifier.

      • id string required
    • ImageSpecificationFamily

      Specifies the image to use by its family name.

      • family string required

        The family name of the image.

  • user_data string optional

    An instance configuration string specified in a valid cloud-init user-data format. You can use this field to configure your instance on launch. The user data string must be plain text and cannot exceed 1MB in size.

    • Format: password
  • tags array of RequestedTagEntry optional

    Key/value pairs representing the instance's tags.

    • RequestedTagEntry
      • key string required

        The key of the tag. On instances, keys starting with lambda-ai- are reserved.

        • Maximum length: 55
        • Regex pattern: ^[a-z][a-z0-9-:]+$
      • value string required

        The value of the tag.

        • Maximum length: 128
  • firewall_rulesets array of FirewallRulesetEntry optional

    The firewall rulesets to associate with the instance. The firewall rulesets must exist in the same region as the instance.

    • FirewallRulesetEntry

      Reference to a firewall ruleset.

      • id string required

        The unique identifier of the firewall ruleset.

Response:200

  • data InstanceLaunchResponse required
    • instance_ids array of string required

      The unique identifiers (IDs) of the launched instances.

      • string

Common Error Response Codes

400: Bad Request
  • "instance-operations/launch/file-system-in-wrong-region"
  • "instance-operations/launch/insufficient-capacity"
  • "global/invalid-parameters"
  • "global/object-does-not-exist"
  • "global/quota-exceeded"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/invalid-address"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/launch' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "region_name": "string",
  "instance_type_name": "gpu_8x_a100",
  "ssh_key_names": [
    "my-public-key"
  ],
  "file_system_names": [
    "my-filesystem"
  ],
  "file_system_mounts": [
    {
      "mount_point": "/data/custom-mount-point",
      "file_system_id": "398578a2336b49079e74043f0bd2cfe8"
    }
  ],
  "hostname": "headnode1",
  "name": "My Instance",
  "image": {
    "id": "ddaedf1b7a0e41ac981711504493b242"
  },
  "user_data": "#cloud-config\nruncmd:\n  - echo \"Hello, World\" > /tmp/hello.txt\n",
  "tags": [
    {
      "key": "key1",
      "value": "value1"
    }
  ],
  "firewall_rulesets": [
    {
      "id": "c4d291f47f9d436fa39f58493ce3b50d"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "instance_ids": [
      "0920582c7ff041399e34823a0be62549"
    ]
  }
}
Live
Send a request to see the response.

Restart instances

POST /api/v1/instance-operations/restart

Restarts one or more instances.

Body Parameters

  • instance_ids array of string required

    The unique identifiers (IDs) of the instances to restart.

    • string

Response:200

  • data InstanceRestartResponse required
    • restarted_instances array of Instance required

      The list of instances that were successfully restarted.

      • Instance

        Detailed information about the instance.

        • id string required

          The unique identifier of the instance.

        • name string optional

          If set, the user-provided name of the instance.

          • Minimum length: 0
          • Maximum length: 64
        • ip string optional

          The public IPv4 address of the instance.

        • private_ip string optional

          The private IPv4 address of the instance.

        • status enum required

          The current status of the instance.

          • Possible values:
            • "booting"
            • "active"
            • "unhealthy"
            • "terminated"
            • "terminating"
            • "preempted"
        • ssh_key_names array of string required

          The names of the SSH keys that are allowed to access the instance.

          • string
        • file_system_names array of string required

          The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.

          • string
        • file_system_mounts array of FilesystemMountEntry optional

          The filesystems, along with the mount paths, mounted to the instances. If no filesystems are mounted, this parameter will be missing from the response.

          • FilesystemMountEntry

            The mount point for a filesystem mounted to an instance.

            • mount_point string required

              The absolute path indicating where on the instance the filesystem will be mounted.

            • file_system_id string required

              The id of the filesystem to mount to the instance.

        • region Region required

          The region in which the instance is deployed.

          • name string required

            The region code.

          • description string required

            The region description.

        • instance_type InstanceType required

          Detailed information about the instance's instance type.

          • name string required

            The name of the instance type.

          • description string required

            A description of the instance type.

          • gpu_description string required

            The type of GPU used by this instance type.

          • price_cents_per_hour integer required

            The price of the instance type in US cents per hour.

          • specs InstanceTypeSpecs required

            Detailed technical specifications for the instance type.

            • vcpus integer required

              The number of virtual CPUs.

            • memory_gib integer required

              The amount of RAM in gibibytes (GiB).

            • storage_gib integer required

              The amount of storage in gibibytes (GiB).

            • gpus integer required

              The number of GPUs.

          • architecture enum required

            The CPU architecture of the instance type.

            • Possible values:
              • "x86_64"
              • "arm64"
        • image InstanceImage optional

          The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

          • id string required

            The unique identifier (ID) of the image.

          • family string required

            The family the image belongs to.

        • hostname string optional

          The hostname assigned to this instance, which resolves to the instance's IP.

        • jupyter_token string optional

          The secret token used to log into the JupyterLab server hosted on the instance.

        • jupyter_url string optional

          The URL that opens the JupyterLab environment on the instance.

        • first_healthy (string | null) required

          When the instance first became healthy, or null if it never has.

          Any of
          • string
            • Format: date-time
          • null
        • actions InstanceActionAvailability required

          A set of status objects representing the current availability of common instance operations.

          • migrate InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • rebuild InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • restart InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • cold_reboot InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

            Deprecated: use power_cycle instead, which reports the same availability.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • power_cycle InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently eligible for a power cycle. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • terminate InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • tags array of TagEntry optional

          Key/value pairs representing the instance's tags.

          • TagEntry
            • key string required

              The key of the tag.

            • value string required

              The value of the tag.

        • firewall_rulesets array of FirewallRulesetEntry optional

          The firewall rulesets associated with this instance.

          • FirewallRulesetEntry

            Reference to a firewall ruleset.

            • id string required

              The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
409: Conflict
  • "global/conflict"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/restart' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "instance_ids": [
    "0920582c7ff041399e34823a0be62549"
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "restarted_instances": [
      {
        "id": "0920582c7ff041399e34823a0be62549",
        "name": "My Instance",
        "ip": "198.51.100.2",
        "private_ip": "10.0.2.100",
        "status": "active",
        "ssh_key_names": [
          "My SSH key"
        ],
        "file_system_names": [
          "my-filesystem"
        ],
        "file_system_mounts": [
          {
            "mount_point": "/lambda/nfs/my-filesystem",
            "file_system_id": "a098b0c7ff041399e34823a0be62549"
          }
        ],
        "region": {
          "name": "us-west-1",
          "description": "California, USA"
        },
        "instance_type": {
          "name": "gpu_8x_example",
          "description": "8x Example GPU (40 GB SXM4)",
          "gpu_description": "Example GPU (40 GB SXM4)",
          "price_cents_per_hour": 1592,
          "specs": {
            "vcpus": 124,
            "memory_gib": 1800,
            "storage_gib": 6144,
            "gpus": 8
          },
          "architecture": "x86_64"
        },
        "workspace_id": "c8f3a2b17ff041399e34823a0be62549",
        "image": {
          "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
          "family": "ubuntu-lts"
        },
        "hostname": "198.51.100.2",
        "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
        "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
        "is_reserved": false,
        "first_healthy": "2023-01-01T00:00:00Z",
        "actions": {
          "migrate": {
            "available": true
          },
          "rebuild": {
            "available": true
          },
          "restart": {
            "available": true
          },
          "cold_reboot": {
            "available": true
          },
          "power_cycle": {
            "available": true
          },
          "terminate": {
            "available": true
          }
        },
        "tags": [
          {
            "key": "key1",
            "value": "value1"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ]
      }
    ]
  }
}
Live
Send a request to see the response.

Terminate instances

POST /api/v1/instance-operations/terminate

Terminates one or more instances.

Body Parameters

  • instance_ids array of string required

    The unique identifiers (IDs) of the instances to terminate.

    • string

Response:200

  • data InstanceTerminateResponse required
    • terminated_instances array of Instance required

      The list of instances that were successfully terminated.

      • Instance

        Detailed information about the instance.

        • id string required

          The unique identifier of the instance.

        • name string optional

          If set, the user-provided name of the instance.

          • Minimum length: 0
          • Maximum length: 64
        • ip string optional

          The public IPv4 address of the instance.

        • private_ip string optional

          The private IPv4 address of the instance.

        • status enum required

          The current status of the instance.

          • Possible values:
            • "booting"
            • "active"
            • "unhealthy"
            • "terminated"
            • "terminating"
            • "preempted"
        • ssh_key_names array of string required

          The names of the SSH keys that are allowed to access the instance.

          • string
        • file_system_names array of string required

          The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.

          • string
        • file_system_mounts array of FilesystemMountEntry optional

          The filesystems, along with the mount paths, mounted to the instances. If no filesystems are mounted, this parameter will be missing from the response.

          • FilesystemMountEntry

            The mount point for a filesystem mounted to an instance.

            • mount_point string required

              The absolute path indicating where on the instance the filesystem will be mounted.

            • file_system_id string required

              The id of the filesystem to mount to the instance.

        • region Region required

          The region in which the instance is deployed.

          • name string required

            The region code.

          • description string required

            The region description.

        • instance_type InstanceType required

          Detailed information about the instance's instance type.

          • name string required

            The name of the instance type.

          • description string required

            A description of the instance type.

          • gpu_description string required

            The type of GPU used by this instance type.

          • price_cents_per_hour integer required

            The price of the instance type in US cents per hour.

          • specs InstanceTypeSpecs required

            Detailed technical specifications for the instance type.

            • vcpus integer required

              The number of virtual CPUs.

            • memory_gib integer required

              The amount of RAM in gibibytes (GiB).

            • storage_gib integer required

              The amount of storage in gibibytes (GiB).

            • gpus integer required

              The number of GPUs.

          • architecture enum required

            The CPU architecture of the instance type.

            • Possible values:
              • "x86_64"
              • "arm64"
        • image InstanceImage optional

          The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

          • id string required

            The unique identifier (ID) of the image.

          • family string required

            The family the image belongs to.

        • hostname string optional

          The hostname assigned to this instance, which resolves to the instance's IP.

        • jupyter_token string optional

          The secret token used to log into the JupyterLab server hosted on the instance.

        • jupyter_url string optional

          The URL that opens the JupyterLab environment on the instance.

        • first_healthy (string | null) required

          When the instance first became healthy, or null if it never has.

          Any of
          • string
            • Format: date-time
          • null
        • actions InstanceActionAvailability required

          A set of status objects representing the current availability of common instance operations.

          • migrate InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • rebuild InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • restart InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • cold_reboot InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

            Deprecated: use power_cycle instead, which reports the same availability.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • power_cycle InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently eligible for a power cycle. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

          • terminate InstanceActionAvailabilityDetails required

            Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

            • available boolean required

              If set, indicates that the relevant operation can be performed on the instance in its current state.

            • reason_code (enum | string) optional

              A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

              Any of
              • enum
                • Possible values:
                  • "vm-has-not-launched"
                  • "vm-is-too-old"
                  • "vm-is-terminating"
                  • "vm-action-in-progress"
                  • "vm-action-unavailable-bare-metal"
                  • "vm-action-unavailable-virtualized"
              • string
            • reason_description string optional

              A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • tags array of TagEntry optional

          Key/value pairs representing the instance's tags.

          • TagEntry
            • key string required

              The key of the tag.

            • value string required

              The value of the tag.

        • firewall_rulesets array of FirewallRulesetEntry optional

          The firewall rulesets associated with this instance.

          • FirewallRulesetEntry

            Reference to a firewall ruleset.

            • id string required

              The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instance-operations/terminate' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "instance_ids": [
    "0920582c7ff041399e34823a0be62549"
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "terminated_instances": [
      {
        "id": "0920582c7ff041399e34823a0be62549",
        "name": "My Instance",
        "ip": "198.51.100.2",
        "private_ip": "10.0.2.100",
        "status": "terminating",
        "ssh_key_names": [
          "My SSH key"
        ],
        "file_system_names": [
          "my-filesystem"
        ],
        "file_system_mounts": [
          {
            "mount_point": "/lambda/nfs/my-filesystem",
            "file_system_id": "a098b0c7ff041399e34823a0be62549"
          }
        ],
        "region": {
          "name": "us-west-1",
          "description": "California, USA"
        },
        "instance_type": {
          "name": "gpu_8x_example",
          "description": "8x Example GPU (40 GB SXM4)",
          "gpu_description": "Example GPU (40 GB SXM4)",
          "price_cents_per_hour": 1592,
          "specs": {
            "vcpus": 124,
            "memory_gib": 1800,
            "storage_gib": 6144,
            "gpus": 8
          },
          "architecture": "x86_64"
        },
        "workspace_id": "c8f3a2b17ff041399e34823a0be62549",
        "image": {
          "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
          "family": "ubuntu-lts"
        },
        "hostname": "198.51.100.2",
        "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
        "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
        "is_reserved": false,
        "first_healthy": "2023-01-01T00:00:00Z",
        "actions": {
          "migrate": {
            "available": true
          },
          "rebuild": {
            "available": true
          },
          "restart": {
            "available": true
          },
          "cold_reboot": {
            "available": true
          },
          "power_cycle": {
            "available": true
          },
          "terminate": {
            "available": true
          }
        },
        "tags": [
          {
            "key": "key1",
            "value": "value1"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ]
      }
    ]
  }
}
Live
Send a request to see the response.

List available instance types

GET /api/v1/instance-types

Retrieves a list of the instance types currently offered on Lambda's public cloud, as well as details about each type. Details include resource specifications, pricing, and regional availability.

Parameters

There are no parameters for this endpoint.

Response:200

  • data InstanceTypes required
    • <string> InstanceTypesItem optional

      Detailed information and regional availability for the instance type.

      • instance_type InstanceType required

        The description, technical specifications, and metadata for this instance type.

        • name string required

          The name of the instance type.

        • description string required

          A description of the instance type.

        • gpu_description string required

          The type of GPU used by this instance type.

        • price_cents_per_hour integer required

          The price of the instance type in US cents per hour.

        • specs InstanceTypeSpecs required

          Detailed technical specifications for the instance type.

          • vcpus integer required

            The number of virtual CPUs.

          • memory_gib integer required

            The amount of RAM in gibibytes (GiB).

          • storage_gib integer required

            The amount of storage in gibibytes (GiB).

          • gpus integer required

            The number of GPUs.

        • architecture enum required

          The CPU architecture of the instance type.

          • Possible values:
            • "x86_64"
            • "arm64"
      • regions_with_capacity_available array of Region required

        A list of the regions in which this instance type is available.

        • Region
          • name string required

            The region code.

          • description string required

            The region description.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instance-types' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "gpu_8x_example": {
      "instance_type": {
        "name": "gpu_8x_example",
        "description": "8x Example GPU (40 GB SXM4)",
        "gpu_description": "Example GPU (40 GB SXM4)",
        "price_cents_per_hour": 1592,
        "specs": {
          "vcpus": 124,
          "memory_gib": 1800,
          "storage_gib": 6144,
          "gpus": 8
        },
        "architecture": "x86_64"
      },
      "regions_with_capacity_available": [
        {
          "name": "us-west-1",
          "description": "California, USA"
        }
      ]
    }
  }
}
Live
Send a request to see the response.

List running instances

GET /api/v1/instances

Retrieves a list of your running instances.

Pagination is opt-in. If you send neither page_size nor page_token, the response contains every instance, oldest first, and page_token is null. If you send either, results are paged newest first, page_size (default 50) per page; pass the returned page_token to get the next page.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • cluster_id string optional

    If provided, the resulting list will only include instances that are part of a cluster with this unique identifier (ID).

Response:200

  • data array of Instance required
    • Instance

      Detailed information about the instance.

      • id string required

        The unique identifier of the instance.

      • name string optional

        If set, the user-provided name of the instance.

        • Minimum length: 0
        • Maximum length: 64
      • ip string optional

        The public IPv4 address of the instance.

      • private_ip string optional

        The private IPv4 address of the instance.

      • status enum required

        The current status of the instance.

        • Possible values:
          • "booting"
          • "active"
          • "unhealthy"
          • "terminated"
          • "terminating"
          • "preempted"
      • ssh_key_names array of string required

        The names of the SSH keys that are allowed to access the instance.

        • string
      • file_system_names array of string required

        The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.

        • string
      • file_system_mounts array of FilesystemMountEntry optional

        The filesystems, along with the mount paths, mounted to the instances. If no filesystems are mounted, this parameter will be missing from the response.

        • FilesystemMountEntry

          The mount point for a filesystem mounted to an instance.

          • mount_point string required

            The absolute path indicating where on the instance the filesystem will be mounted.

          • file_system_id string required

            The id of the filesystem to mount to the instance.

      • region Region required

        The region in which the instance is deployed.

        • name string required

          The region code.

        • description string required

          The region description.

      • instance_type InstanceType required

        Detailed information about the instance's instance type.

        • name string required

          The name of the instance type.

        • description string required

          A description of the instance type.

        • gpu_description string required

          The type of GPU used by this instance type.

        • price_cents_per_hour integer required

          The price of the instance type in US cents per hour.

        • specs InstanceTypeSpecs required

          Detailed technical specifications for the instance type.

          • vcpus integer required

            The number of virtual CPUs.

          • memory_gib integer required

            The amount of RAM in gibibytes (GiB).

          • storage_gib integer required

            The amount of storage in gibibytes (GiB).

          • gpus integer required

            The number of GPUs.

        • architecture enum required

          The CPU architecture of the instance type.

          • Possible values:
            • "x86_64"
            • "arm64"
      • image InstanceImage optional

        The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

        • id string required

          The unique identifier (ID) of the image.

        • family string required

          The family the image belongs to.

      • hostname string optional

        The hostname assigned to this instance, which resolves to the instance's IP.

      • jupyter_token string optional

        The secret token used to log into the JupyterLab server hosted on the instance.

      • jupyter_url string optional

        The URL that opens the JupyterLab environment on the instance.

      • first_healthy (string | null) required

        When the instance first became healthy, or null if it never has.

        Any of
        • string
          • Format: date-time
        • null
      • actions InstanceActionAvailability required

        A set of status objects representing the current availability of common instance operations.

        • migrate InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • rebuild InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • restart InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • cold_reboot InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

          Deprecated: use power_cycle instead, which reports the same availability.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • power_cycle InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently eligible for a power cycle. If not, describes why the operation is blocked.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

        • terminate InstanceActionAvailabilityDetails required

          Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

          • available boolean required

            If set, indicates that the relevant operation can be performed on the instance in its current state.

          • reason_code (enum | string) optional

            A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

            Any of
            • enum
              • Possible values:
                • "vm-has-not-launched"
                • "vm-is-too-old"
                • "vm-is-terminating"
                • "vm-action-in-progress"
                • "vm-action-unavailable-bare-metal"
                • "vm-action-unavailable-virtualized"
            • string
          • reason_description string optional

            A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • tags array of TagEntry optional

        Key/value pairs representing the instance's tags.

        • TagEntry
          • key string required

            The key of the tag.

          • value string required

            The value of the tag.

      • firewall_rulesets array of FirewallRulesetEntry optional

        The firewall rulesets associated with this instance.

        • FirewallRulesetEntry

          Reference to a firewall ruleset.

          • id string required

            The unique identifier of the firewall ruleset.

  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "0920582c7ff041399e34823a0be62549",
      "name": "My Instance",
      "ip": "198.51.100.2",
      "private_ip": "10.0.2.100",
      "status": "booting",
      "ssh_key_names": [
        "My SSH key"
      ],
      "file_system_names": [
        "my-filesystem"
      ],
      "file_system_mounts": [
        {
          "mount_point": "/data/custom-mount-point",
          "file_system_id": "398578a2336b49079e74043f0bd2cfe8"
        }
      ],
      "region": {
        "name": "string",
        "description": "string"
      },
      "instance_type": {
        "name": "gpu_8x_h100_sxm5gdr",
        "description": "8x H100 (80 GB SXM5)",
        "gpu_description": "H100 (80 GB SXM5)",
        "price_cents_per_hour": 3592,
        "specs": {
          "vcpus": 208,
          "memory_gib": 1800,
          "storage_gib": 24780,
          "gpus": 8
        },
        "architecture": "x86_64"
      },
      "image": {
        "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
        "family": "ubuntu-lts"
      },
      "hostname": "headnode1",
      "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
      "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
      "first_healthy": "1970-01-01T00:00:00.000Z",
      "actions": {
        "migrate": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        },
        "rebuild": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        },
        "restart": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        },
        "cold_reboot": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        },
        "power_cycle": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        },
        "terminate": {
          "available": false,
          "reason_code": "vm-has-not-launched",
          "reason_description": "string"
        }
      },
      "tags": [
        {
          "key": "key1",
          "value": "value1"
        }
      ],
      "firewall_rulesets": [
        {
          "id": "c4d291f47f9d436fa39f58493ce3b50d"
        }
      ]
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Retrieve instance details

GET /api/v1/instances/{id}

Retrieves the details of a specific instance, including whether or not the instance is running.

Path Parameters

  • id string required

    The unique identifier (ID) of the instance

Response:200

  • data Instance required

    Detailed information about the instance.

    • id string required

      The unique identifier of the instance.

    • name string optional

      If set, the user-provided name of the instance.

      • Minimum length: 0
      • Maximum length: 64
    • ip string optional

      The public IPv4 address of the instance.

    • private_ip string optional

      The private IPv4 address of the instance.

    • status enum required

      The current status of the instance.

      • Possible values:
        • "booting"
        • "active"
        • "unhealthy"
        • "terminated"
        • "terminating"
        • "preempted"
    • ssh_key_names array of string required

      The names of the SSH keys that are allowed to access the instance.

      • string
    • file_system_names array of string required

      The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.

      • string
    • file_system_mounts array of FilesystemMountEntry optional

      The filesystems, along with the mount paths, mounted to the instances. If no filesystems are mounted, this parameter will be missing from the response.

      • FilesystemMountEntry

        The mount point for a filesystem mounted to an instance.

        • mount_point string required

          The absolute path indicating where on the instance the filesystem will be mounted.

        • file_system_id string required

          The id of the filesystem to mount to the instance.

    • region Region required

      The region in which the instance is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • instance_type InstanceType required

      Detailed information about the instance's instance type.

      • name string required

        The name of the instance type.

      • description string required

        A description of the instance type.

      • gpu_description string required

        The type of GPU used by this instance type.

      • price_cents_per_hour integer required

        The price of the instance type in US cents per hour.

      • specs InstanceTypeSpecs required

        Detailed technical specifications for the instance type.

        • vcpus integer required

          The number of virtual CPUs.

        • memory_gib integer required

          The amount of RAM in gibibytes (GiB).

        • storage_gib integer required

          The amount of storage in gibibytes (GiB).

        • gpus integer required

          The number of GPUs.

      • architecture enum required

        The CPU architecture of the instance type.

        • Possible values:
          • "x86_64"
          • "arm64"
    • image InstanceImage optional

      The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

      • id string required

        The unique identifier (ID) of the image.

      • family string required

        The family the image belongs to.

    • hostname string optional

      The hostname assigned to this instance, which resolves to the instance's IP.

    • jupyter_token string optional

      The secret token used to log into the JupyterLab server hosted on the instance.

    • jupyter_url string optional

      The URL that opens the JupyterLab environment on the instance.

    • first_healthy (string | null) required

      When the instance first became healthy, or null if it never has.

      Any of
      • string
        • Format: date-time
      • null
    • actions InstanceActionAvailability required

      A set of status objects representing the current availability of common instance operations.

      • migrate InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • rebuild InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • restart InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • cold_reboot InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

        Deprecated: use power_cycle instead, which reports the same availability.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • power_cycle InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently eligible for a power cycle. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • terminate InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

    • tags array of TagEntry optional

      Key/value pairs representing the instance's tags.

      • TagEntry
        • key string required

          The key of the tag.

        • value string required

          The value of the tag.

    • firewall_rulesets array of FirewallRulesetEntry optional

      The firewall rulesets associated with this instance.

      • FirewallRulesetEntry

        Reference to a firewall ruleset.

        • id string required

          The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/instances/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "name": "My Instance",
    "ip": "198.51.100.2",
    "private_ip": "10.0.2.100",
    "status": "booting",
    "ssh_key_names": [
      "My SSH key"
    ],
    "file_system_names": [
      "my-filesystem"
    ],
    "file_system_mounts": [
      {
        "mount_point": "/data/custom-mount-point",
        "file_system_id": "398578a2336b49079e74043f0bd2cfe8"
      }
    ],
    "region": {
      "name": "string",
      "description": "string"
    },
    "instance_type": {
      "name": "gpu_8x_h100_sxm5gdr",
      "description": "8x H100 (80 GB SXM5)",
      "gpu_description": "H100 (80 GB SXM5)",
      "price_cents_per_hour": 3592,
      "specs": {
        "vcpus": 208,
        "memory_gib": 1800,
        "storage_gib": 24780,
        "gpus": 8
      },
      "architecture": "x86_64"
    },
    "image": {
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
      "family": "ubuntu-lts"
    },
    "hostname": "headnode1",
    "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
    "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
    "first_healthy": "1970-01-01T00:00:00.000Z",
    "actions": {
      "migrate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "rebuild": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "restart": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "cold_reboot": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "power_cycle": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "terminate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      }
    },
    "tags": [
      {
        "key": "key1",
        "value": "value1"
      }
    ],
    "firewall_rulesets": [
      {
        "id": "c4d291f47f9d436fa39f58493ce3b50d"
      }
    ]
  }
}
Live
Send a request to see the response.

Update instance details

POST /api/v1/instances/{id}

Updates the details of the specified instance.

Path Parameters

  • id string required

    The unique identifier (ID) of the instance

Body Parameters

  • name string optional

    The new, user-provided name for the instance.

    • Minimum length: 0
    • Maximum length: 64
  • tags array of RequestedTagEntry optional

    The new tags for the instance. If provided, this replaces the existing tags (an empty list clears them). If not provided, the tags will not be updated.

    • RequestedTagEntry
      • key string required

        The key of the tag. On instances, keys starting with lambda-ai- are reserved.

        • Maximum length: 55
        • Regex pattern: ^[a-z][a-z0-9-:]+$
      • value string required

        The value of the tag.

        • Maximum length: 128

Response:200

  • data Instance required

    Detailed information about the instance.

    • id string required

      The unique identifier of the instance.

    • name string optional

      If set, the user-provided name of the instance.

      • Minimum length: 0
      • Maximum length: 64
    • ip string optional

      The public IPv4 address of the instance.

    • private_ip string optional

      The private IPv4 address of the instance.

    • status enum required

      The current status of the instance.

      • Possible values:
        • "booting"
        • "active"
        • "unhealthy"
        • "terminated"
        • "terminating"
        • "preempted"
    • ssh_key_names array of string required

      The names of the SSH keys that are allowed to access the instance.

      • string
    • file_system_names array of string required

      The names of the filesystems mounted to the instance. If no filesystems are mounted, this array is empty.

      • string
    • file_system_mounts array of FilesystemMountEntry optional

      The filesystems, along with the mount paths, mounted to the instances. If no filesystems are mounted, this parameter will be missing from the response.

      • FilesystemMountEntry

        The mount point for a filesystem mounted to an instance.

        • mount_point string required

          The absolute path indicating where on the instance the filesystem will be mounted.

        • file_system_id string required

          The id of the filesystem to mount to the instance.

    • region Region required

      The region in which the instance is deployed.

      • name string required

        The region code.

      • description string required

        The region description.

    • instance_type InstanceType required

      Detailed information about the instance's instance type.

      • name string required

        The name of the instance type.

      • description string required

        A description of the instance type.

      • gpu_description string required

        The type of GPU used by this instance type.

      • price_cents_per_hour integer required

        The price of the instance type in US cents per hour.

      • specs InstanceTypeSpecs required

        Detailed technical specifications for the instance type.

        • vcpus integer required

          The number of virtual CPUs.

        • memory_gib integer required

          The amount of RAM in gibibytes (GiB).

        • storage_gib integer required

          The amount of storage in gibibytes (GiB).

        • gpus integer required

          The number of GPUs.

      • architecture enum required

        The CPU architecture of the instance type.

        • Possible values:
          • "x86_64"
          • "arm64"
    • image InstanceImage optional

      The machine image the instance booted from. Absent when it can no longer be resolved, such as for a terminated instance.

      • id string required

        The unique identifier (ID) of the image.

      • family string required

        The family the image belongs to.

    • hostname string optional

      The hostname assigned to this instance, which resolves to the instance's IP.

    • jupyter_token string optional

      The secret token used to log into the JupyterLab server hosted on the instance.

    • jupyter_url string optional

      The URL that opens the JupyterLab environment on the instance.

    • first_healthy (string | null) required

      When the instance first became healthy, or null if it never has.

      Any of
      • string
        • Format: date-time
      • null
    • actions InstanceActionAvailability required

      A set of status objects representing the current availability of common instance operations.

      • migrate InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be migrated. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • rebuild InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be rebuilt. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • restart InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be restarted. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • cold_reboot InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently eligible for a cold reboot. If not, describes why the operation is blocked.

        Deprecated: use power_cycle instead, which reports the same availability.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • power_cycle InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently eligible for a power cycle. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

      • terminate InstanceActionAvailabilityDetails required

        Indicates whether the instance is currently able to be terminated. If not, describes why the operation is blocked.

        • available boolean required

          If set, indicates that the relevant operation can be performed on the instance in its current state.

        • reason_code (enum | string) optional

          A code representing the instance state that is blocking the operation. Only provided if the operation is blocked.

          Any of
          • enum
            • Possible values:
              • "vm-has-not-launched"
              • "vm-is-too-old"
              • "vm-is-terminating"
              • "vm-action-in-progress"
              • "vm-action-unavailable-bare-metal"
              • "vm-action-unavailable-virtualized"
          • string
        • reason_description string optional

          A longer description of why this operation is currently blocked. Only provided if the operation is blocked.

    • tags array of TagEntry optional

      Key/value pairs representing the instance's tags.

      • TagEntry
        • key string required

          The key of the tag.

        • value string required

          The value of the tag.

    • firewall_rulesets array of FirewallRulesetEntry optional

      The firewall rulesets associated with this instance.

      • FirewallRulesetEntry

        Reference to a firewall ruleset.

        • id string required

          The unique identifier of the firewall ruleset.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/instances/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Instance",
  "tags": [
    {
      "key": "key1",
      "value": "value1"
    }
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "name": "My Instance",
    "ip": "198.51.100.2",
    "private_ip": "10.0.2.100",
    "status": "booting",
    "ssh_key_names": [
      "My SSH key"
    ],
    "file_system_names": [
      "my-filesystem"
    ],
    "file_system_mounts": [
      {
        "mount_point": "/data/custom-mount-point",
        "file_system_id": "398578a2336b49079e74043f0bd2cfe8"
      }
    ],
    "region": {
      "name": "string",
      "description": "string"
    },
    "instance_type": {
      "name": "gpu_8x_h100_sxm5gdr",
      "description": "8x H100 (80 GB SXM5)",
      "gpu_description": "H100 (80 GB SXM5)",
      "price_cents_per_hour": 3592,
      "specs": {
        "vcpus": 208,
        "memory_gib": 1800,
        "storage_gib": 24780,
        "gpus": 8
      },
      "architecture": "x86_64"
    },
    "image": {
      "id": "43336648-096d-4cba-9aa2-f9bb7727639d",
      "family": "ubuntu-lts"
    },
    "hostname": "headnode1",
    "jupyter_token": "03b7d30d9d3e4d8fa41657bc0d478c1b",
    "jupyter_url": "https://jupyter-249e1ccff1894822af39ac822637f881.lambdaspaces.com/?token=03b7d30d9d3e4d8fa41657bc0d478c1b",
    "first_healthy": "1970-01-01T00:00:00.000Z",
    "actions": {
      "migrate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "rebuild": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "restart": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "cold_reboot": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "power_cycle": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      },
      "terminate": {
        "available": false,
        "reason_code": "vm-has-not-launched",
        "reason_description": "string"
      }
    },
    "tags": [
      {
        "key": "key1",
        "value": "value1"
      }
    ],
    "firewall_rulesets": [
      {
        "id": "c4d291f47f9d436fa39f58493ce3b50d"
      }
    ]
  }
}
Live
Send a request to see the response.

Regions

List regions

GET /api/v1/regions

Retrieves a list of available regions.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of Region required
    • Region
      • name string required

        The region code.

      • description string required

        The region description.

Common Error Response Codes

401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/regions' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "name": "string",
      "description": "string"
    }
  ]
}
Live
Send a request to see the response.

Roles

Predefined and custom roles, and where each is assigned.

List all roles

GET /api/v1/roles

Retrieves the roles available to the requestor.

Query Parameters

  • page_size integer optional

    Maximum number of results per page. Can be between 1 and 100. The default is 50.

  • page_token string optional

    A page token for cursor-based pagination.

  • search string optional

    Search against the role name and description. Unless order_by is given, results are ranked best match first.

    • Maximum length: 128
  • role_type enum optional

    Filter to account roles or workspace roles. If omitted, both are returned.

    • Possible values:
      • "account"
      • "workspace"
  • is_builtin boolean optional

    Filter to built-in roles (true) or custom roles (false). If omitted, both are returned.

  • permission_ids array of string optional

    Only return roles that grant every listed permission. Repeat the parameter to require several.

    • string
  • order_by enum optional

    The field to sort by. Defaults to relevance when search is given and created_at otherwise. relevance requires search.

    • Possible values:
      • "name"
      • "description"
      • "role_type"
      • "is_builtin"
      • "created_at"
      • "relevance"
  • direction enum optional

    The sort direction. Defaults to desc for created_at and relevance and asc for every other field.

    • Possible values:
      • "asc"
      • "desc"

Response:200

  • data array of Role required
    • Role
      • id string required

        The unique identifier (ID) of the role.

      • name string required

        The name of the role.

      • role_type enum required

        The type of the role.

        • Possible values:
          • "account"
          • "workspace"
      • description (string | null) required

        The description of the role.

        Any of
        • string
        • null
      • permission_ids array of string required

        The permissions included in the role.

        • string
      • is_builtin boolean required

        Whether the role is a built-in (predefined) role.

      • created_at string required

        The time the role was created.

        • Format: date-time
  • page_token (string | null) required

    Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

    Any of
    • string
    • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample
Press Enter to add multiple values.

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/roles' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "name": "string",
      "role_type": "account",
      "description": "string",
      "permission_ids": [
        "string"
      ],
      "is_builtin": false,
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "page_token": "eyJuZXh0IjoxNzA0MTk2ODAwfQ=="
}
Live
Send a request to see the response.

Get role details

GET /api/v1/roles/{role_id}

Retrieves details about the specified role.

Path Parameters

  • role_id string required

    The unique identifier (ID) of the role.

Response:200

  • data Role required
    • id string required

      The unique identifier (ID) of the role.

    • name string required

      The name of the role.

    • role_type enum required

      The type of the role.

      • Possible values:
        • "account"
        • "workspace"
    • description (string | null) required

      The description of the role.

      Any of
      • string
      • null
    • permission_ids array of string required

      The permissions included in the role.

      • string
    • is_builtin boolean required

      Whether the role is a built-in (predefined) role.

    • created_at string required

      The time the role was created.

      • Format: date-time

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/roles/7bd64c8f8a89497384b4deb454fc4293' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "name": "string",
    "role_type": "account",
    "description": "string",
    "permission_ids": [
      "string"
    ],
    "is_builtin": false,
    "created_at": "1970-01-01T00:00:00.000Z"
  }
}
Live
Send a request to see the response.

SSH keys

List your SSH keys

GET /api/v1/ssh-keys

Retrieves a list of your SSH keys.

Parameters

There are no parameters for this endpoint.

Response:200

  • data array of SSHKey required
    • SSHKey

      Information about a stored SSH key that can be used to access instances over SSH.

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddf9a910ceb744a0bb95242cbba6cb50",
      "name": "my-public-key",
      "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname"
    }
  ]
}
Live
Send a request to see the response.

Add an SSH key

POST /api/v1/ssh-keys

Add an SSH key to your Lambda Cloud account. You can upload an existing public key, or you can generate a new key pair.

  • To use an existing key pair, set the public_key property in the request body to your public key.

  • To generate a new key pair, omit the public_key property from the request body.

warning
Important

Lambda doesn't store your private key after it's been generated. If you generate a new key pair, make sure to save the resulting private key locally.

For example, to generate a new key pair and associate it with a Lambda On-Demand Cloud instance:

  1. Generate the key pair. The command provided below automatically extracts and saves the returned private key to a new file called key.pem. Replace <NEW-KEY-NAME> with the name you want to assign to the SSH key:

    curl --request POST --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
--fail \
--header "Authorization: Bearer ${LAMBDA_API_KEY}" \
--data '{"name": "<NEW-KEY-NAME>"}' \
| jq -r '.data.private_key' > key.pem

  2. Next, set the private key's permissions to read-only:

    chmod 400 key.pem

  3. Launch a new instance. Replace <NEW-KEY-NAME> with the name you assigned to your SSH key.

    curl --request POST 'https://cloud.lambda.ai/api/v1/instance-operations/launch' \
--fail \
--header "Authorization: Bearer ${LAMBDA_API_KEY}" \
--data '{"region_name":"us-west-1","instance_type_name":"gpu_1x_a10","ssh_key_names":["<NEW-KEY-NAME>"],"file_system_names":[],"quantity":1,"name":"My Instance"}'

  4. From your local terminal, establish an SSH connection to the instance. Replace <INSTANCE-IP> with the public IP of the instance:

    ssh -i key.pem <INSTANCE-IP>

Body Parameters

  • name string required

    The name of the SSH key.

    • Minimum length: 1
    • Maximum length: 64
  • public_key string optional

    The public key to store. Omit this to generate a new key pair.

    • Minimum length: 1
    • Maximum length: 4096

Response:200

  • data (GeneratedSSHKey | SSHKey) required
    Any of
    • GeneratedSSHKey

      Information about a server-generated SSH key.

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096
      • private_key string required

        The private key generated in the SSH key pair. Store this value locally; Lambda does not retain the private key server-side.

    • SSHKey

      Information about a stored SSH key that can be used to access instances over SSH.

      • id string required

        The unique identifier (ID) of the SSH key.

      • name string required

        The name of the SSH key.

        • Minimum length: 1
        • Maximum length: 64
      • public_key string required

        The public key for the SSH key.

        • Minimum length: 1
        • Maximum length: 4096

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/ssh-keys' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "my-public-key",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddf9a910ceb744a0bb95242cbba6cb50",
    "name": "my-public-key",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICN+lJwsONkwrdsSnQsu1ydUkIuIg5oOC+Eslvmtt60T noname",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----\\n"
  }
}
Live
Send a request to see the response.

Delete an SSH key

DELETE /api/v1/ssh-keys/{id}

Deletes the specified SSH key.

Path Parameters

  • id string required

    The unique identifier (ID) of the SSH key to delete

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/ssh-keys/ddf9a910ceb744a0bb95242cbba6cb50' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

Support Tickets

The Lambda Support Ticketing API is currently in beta. Contact support to enable access.

List support tickets

GET /api/v1/tickets

Retrieves a list of support tickets for your account.

Query Parameters

  • status array of enum optional

    The current status of a support ticket.

    • enum

      The current status of a support ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
  • type array of enum optional

    The type of support ticket.

    • enum

      The type of support ticket.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
  • severity array of enum optional

    The severity level for incident tickets.

    • enum

      The severity level for incident tickets.

      • Possible values:
        • "sev_1"
        • "sev_2"
        • "sev_3"
  • priority array of enum optional

    The priority level of a support ticket.

    • enum

      The priority level of a support ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
  • device_serial array of string optional

    The serial number of the affected device. Matching is case-insensitive.

    • string
  • order_by enum optional

    Specifies the field used to sort the list of tickets.

    • Possible values:
      • "created_at"
      • "updated_at"
  • direction enum optional

    Specifies the order in which to sort the list of tickets.

    • Possible values:
      • "asc"
      • "desc"
  • page_token string optional

    A page token. Provide this token in your next request to retrieve the next page of results. If there are no additional pages, this field has a null value.

Response:200

  • data TicketListResponse required
    • tickets array of Ticket required

      The current page of tickets.

      • Ticket
        • id string required

          The unique identifier for the ticket.

        • subject string required

          A short summary of the issue.

        • description string required

          The initial text provided when creating the issue or request.

        • type enum optional

          The type of support ticket.

          • Possible values:
            • "service_request"
            • "incident"
            • "automated_event"
        • severity enum optional

          The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.

          • Possible values:
            • "sev_1"
            • "sev_2"
            • "sev_3"
        • priority enum optional

          The priority level of the ticket.

          • Possible values:
            • "low"
            • "normal"
            • "high"
            • "urgent"
        • status enum required

          The current status of the ticket.

          • Possible values:
            • "open"
            • "on_hold"
            • "pending"
            • "solved"
            • "confirm_solved"
        • external_ticket_provider string optional

          The external ticketing provider name (e.g., "zendesk").

        • external_ticket_id string optional

          The external provider ticket ID (e.g., Zendesk ticket ID).

        • hostname string optional

          The hostname of the affected device.

        • device_serial string optional

          The serial number of the affected device.

        • created_at string required

          The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.

          • Format: date-time
        • updated_at string optional

          The date and time at which the ticket was last updated. Formatted as an ISO 8601 timestamp.

          • Format: date-time
        • resolved_at string optional

          The date and time at which the ticket was resolved. Formatted as an ISO 8601 timestamp.

          • Format: date-time
        • affected_devices array of string optional

          The list of devices affected by the issue.

          • string
        • comments array of TicketComment required

          The ticket's full comment history.

          • TicketComment
            • body string required

              Comment text.

            • author string required

              The identifier of the comment author.

            • created_at string required

              The date and time at which the comment was created. Formatted as an ISO 8601 timestamp.

              • Format: date-time
    • page_token (string | null) required

      A page token. Provide this token in your next request to retrieve the next page of results. Null if there are no additional pages.

      Any of
      • string
      • null

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.
Press Enter to add multiple values.

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "tickets": [
      {
        "id": "0920582c7ff041399e34823a0be62549",
        "subject": "Node 12345 is experiencing an issue",
        "description": "Performance drops by 30-40% during peak hours..",
        "type": "incident",
        "severity": "sev_1",
        "priority": "high",
        "status": "open",
        "external_ticket_provider": "zendesk",
        "external_ticket_id": "12345",
        "hostname": "abc-gpu-001",
        "device_serial": "SN123456789",
        "created_at": "2024-10-20T10:15:00Z",
        "updated_at": "2024-10-23T14:30:00Z",
        "resolved_at": "2024-10-25T09:00:00Z",
        "affected_devices": [
          "abc-gpu-001",
          "abc-gpu-002"
        ],
        "comments": [
          {
            "body": "Instance is experiencing high latency on GPU operations",
            "author": "support-agent-123",
            "created_at": "2024-10-23T14:30:00Z"
          }
        ]
      }
    ],
    "page_token": "string"
  }
}
Live
Send a request to see the response.

Create a support ticket

POST /api/v1/tickets

Creates a new support ticket.

Body Parameters

  • subject string required

    A short summary of the issue.

  • description string required

    An initial description of the issue or request. When you make an API request to list the comments on this ticket, this will appear as the first public comment in the list.

  • type enum required

    The type of support ticket.

    • Possible values:
      • "incident"
      • "service_request"
  • severity enum optional

    The severity level of the issue. Required for incident tickets, must not be provided for service requests.

    • Possible values:
      • "sev_1"
      • "sev_2"
      • "sev_3"
  • priority enum optional

    The priority level of the ticket.

    • Possible values:
      • "low"
      • "normal"
      • "high"
      • "urgent"
  • ip string optional

    The IP address of the affected node.

  • instance_id string optional

    The ID of the affected on-demand instance.

  • cluster_id string optional

    The ID of the affected 1CC or Supercluster.

  • hostname string optional

    The hostname of the affected device.

  • device_serial string optional

    The serial number of the affected device.

  • requester_email string optional

    The email address to associate with the ticket's requester.

  • affected_devices array of string optional

    The list of devices affected by the issue.

    • string

Response:200

  • data TicketCreateResponse required
    • id string required

      The unique identifier for the ticket.

    • external_ticket_provider string optional

      The external ticketing provider name (e.g., "zendesk").

    • external_ticket_id string optional

      The external provider ticket ID (e.g., Zendesk ticket ID).

    • status enum required

      The current status of the ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
    • type enum required

      The type of issue or request.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
    • severity enum optional

      The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.

      • Possible values:
        • "sev_1"
        • "sev_2"
        • "sev_3"
    • priority enum optional

      The priority level of the ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
    • affected_devices array of string optional

      The list of devices affected by the issue.

      • string
    • hostname string optional

      The hostname of the affected device.

    • device_serial string optional

      The serial number of the affected device.

    • created_at string required

      The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
  • "support-tickets/creation-failed"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/tickets' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "subject": "GPU cluster experiencing performance degradation",
  "description": "Performance drops by 30-40% during peak hours.",
  "type": "incident",
  "severity": "sev_1",
  "priority": "high",
  "ip": "192.222.53.194",
  "instance_id": "2fbb7a309a7c475abe7ee58bd125ac36",
  "cluster_id": "a0bacf07268245a2b596b5863185a4ff",
  "hostname": "abc-gpu-001",
  "device_serial": "SN123456789",
  "requester_email": "alerts@example.com",
  "affected_devices": [
    "abc-gpu-001",
    "abc-gpu-002"
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "external_ticket_provider": "zendesk",
    "external_ticket_id": "12345",
    "status": "open",
    "type": "incident",
    "severity": "sev_1",
    "priority": "high",
    "affected_devices": [
      "abc-gpu-001",
      "abc-gpu-002"
    ],
    "hostname": "abc-gpu-001",
    "device_serial": "SN123456789",
    "created_at": "2024-10-20T10:15:00Z"
  }
}
Live
Send a request to see the response.

Get a support ticket

GET /api/v1/tickets/{ticket_id}

Retrieves a specific support ticket by ID.

Path Parameters

  • ticket_id string required

    The ticket ID.

Response:200

  • data Ticket required
    • id string required

      The unique identifier for the ticket.

    • subject string required

      A short summary of the issue.

    • description string required

      The initial text provided when creating the issue or request.

    • type enum optional

      The type of support ticket.

      • Possible values:
        • "service_request"
        • "incident"
        • "automated_event"
    • severity enum optional

      The severity level of the issue represented by the ticket. Omitted if the ticket isn't an incident.

      • Possible values:
        • "sev_1"
        • "sev_2"
        • "sev_3"
    • priority enum optional

      The priority level of the ticket.

      • Possible values:
        • "low"
        • "normal"
        • "high"
        • "urgent"
    • status enum required

      The current status of the ticket.

      • Possible values:
        • "open"
        • "on_hold"
        • "pending"
        • "solved"
        • "confirm_solved"
    • external_ticket_provider string optional

      The external ticketing provider name (e.g., "zendesk").

    • external_ticket_id string optional

      The external provider ticket ID (e.g., Zendesk ticket ID).

    • hostname string optional

      The hostname of the affected device.

    • device_serial string optional

      The serial number of the affected device.

    • created_at string required

      The date and time at which the ticket was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • updated_at string optional

      The date and time at which the ticket was last updated. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • resolved_at string optional

      The date and time at which the ticket was resolved. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • affected_devices array of string optional

      The list of devices affected by the issue.

      • string
    • comments array of TicketComment required

      The ticket's full comment history.

      • TicketComment
        • body string required

          Comment text.

        • author string required

          The identifier of the comment author.

        • created_at string required

          The date and time at which the comment was created. Formatted as an ISO 8601 timestamp.

          • Format: date-time

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "subject": "Node 12345 is experiencing an issue",
    "description": "Performance drops by 30-40% during peak hours..",
    "type": "incident",
    "severity": "sev_1",
    "priority": "high",
    "status": "open",
    "external_ticket_provider": "zendesk",
    "external_ticket_id": "12345",
    "hostname": "abc-gpu-001",
    "device_serial": "SN123456789",
    "created_at": "2024-10-20T10:15:00Z",
    "updated_at": "2024-10-23T14:30:00Z",
    "resolved_at": "2024-10-25T09:00:00Z",
    "affected_devices": [
      "abc-gpu-001",
      "abc-gpu-002"
    ],
    "comments": [
      {
        "body": "Instance is experiencing high latency on GPU operations",
        "author": "support-agent-123",
        "created_at": "2024-10-23T14:30:00Z"
      }
    ]
  }
}
Live
Send a request to see the response.

Update a support ticket

PATCH /api/v1/tickets/{ticket_id}

Updates a support ticket status, severity, or priority, or adds a comment to the ticket. Returns a 202. Ticket updates happen asynchronously so to see the result of an update, re-query the tickets API.

Path Parameters

  • ticket_id string required

    The ticket ID.

Body Parameters

  • status string optional

    The new status to set the ticket to.

    • Const: "solved"
  • severity enum optional

    The new severity level to set the ticket to.

    • Possible values:
      • "sev_1"
      • "sev_2"
      • "sev_3"
  • priority enum optional

    The new priority level to set the ticket to.

    • Possible values:
      • "low"
      • "normal"
      • "high"
      • "urgent"
  • comment TicketCommentInput optional

    Adds a new comment.

    • body string required

      The text of the new comment.

  • affected_devices array of string optional

    The list of devices affected by the issue.

    • string

Response:202

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "status": "solved",
  "severity": "sev_2",
  "priority": "high",
  "comment": {
    "body": "Turns out this was a non-issue on our end. Closing the ticket."
  },
  "affected_devices": [
    "abc-gpu-001",
    "abc-gpu-002"
  ]
}'
Response
Sample

ResponseStatus: 202 Accepted

{
  "data": {}
}
Live
Send a request to see the response.

List ticket attachments

GET /api/v1/tickets/{ticket_id}/attachments

Retrieves all attachments for a ticket.

Path Parameters

  • ticket_id string required

    The ticket ID.

Query Parameters

  • status enum optional

    The current status of an attachment upload.

    • Possible values:
      • "pending"
      • "uploaded"
      • "failed"
      • "deleted"

Response:200

  • data AttachmentListResponse required

    Response containing list of attachments.

    • attachments array of Attachment required

      Retrieves all attachments associated with the specified ticket. If status is omitted, only uploaded attachments will be returned.

      • Attachment

        Attachment metadata.

        • id string required

          The unique identifier for the attachment.

        • filename string required

          The original filename.

        • content_type string required

          The MIME type of the attached file.

        • size_bytes integer required

          The attached file's size in bytes.

        • upload_status enum required

          The current upload status of the attachment.

          • Possible values:
            • "pending"
            • "uploaded"
            • "failed"
            • "deleted"
        • uploaded_at string optional

          The date and time at which the attachment finished uploading. Formatted as an ISO 8601 timestamp. Omitted if the attachment hasn't been uploaded yet.

          • Format: date-time
        • created_at string required

          The date and time at which the attachment was created. Formatted as an ISO 8601 timestamp.

          • Format: date-time

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "attachments": [
      {
        "id": "0920582c7ff041399e34823a0be62549",
        "filename": "debug-logs.tar.gz",
        "content_type": "application/gzip",
        "size_bytes": 1024000,
        "upload_status": "uploaded",
        "uploaded_at": "2024-10-20T10:15:00Z",
        "created_at": "2024-10-20T10:10:00Z"
      }
    ]
  }
}
Live
Send a request to see the response.

Initiate attachment upload

POST /api/v1/tickets/{ticket_id}/attachments

Start the upload process for a ticket attachment. Returns a presigned URL for direct upload to storage.

Path Parameters

  • ticket_id string required

    The ticket ID.

Body Parameters

  • filename string required

    The original filename.

    • Maximum length: 255
  • content_type string required

    The MIME type of the attachment, such as application/gzip for a .gz file or text/plain for a plaintext file.

  • size_bytes integer required

    The file size in bytes. The file size must be one or more bytes.

    • Minimum : 1

Response:200

  • data AttachmentInitiateResponse required

    Response with upload instructions.

    • attachment_id string required

      The unique identifier for the attachment.

    • upload_url string required

      A presigned URL. Use this URL to directly upload the attachment to storage.

    • upload_method string required

      The HTTP method to use when uploading your attachment (PUT or POST).

    • upload_status enum required

      The current upload status of your attachment.

      • Possible values:
        • "pending"
        • "uploaded"
        • "failed"
        • "deleted"
    • expires_in integer required

      The window of time, in seconds, that the provided presigned URL is available to be uploaded to.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "filename": "debug-logs.tar.gz",
  "content_type": "application/gzip",
  "size_bytes": 1024000
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "attachment_id": "0920582c7ff041399e34823a0be62549",
    "upload_url": "https://s3.amazonaws.com/...presigned-url",
    "upload_method": "PUT",
    "upload_status": "pending",
    "expires_in": 3600
  }
}
Live
Send a request to see the response.

Delete attachment

DELETE /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

Delete an attachment.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments/0920582c7ff041399e34823a0be62549' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

Complete attachment upload

POST /api/v1/tickets/{ticket_id}/attachments/{attachment_id}/complete

Mark attachment upload as complete after client finishes uploading to storage.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data Attachment required

    Attachment metadata.

    • id string required

      The unique identifier for the attachment.

    • filename string required

      The original filename.

    • content_type string required

      The MIME type of the attached file.

    • size_bytes integer required

      The attached file's size in bytes.

    • upload_status enum required

      The current upload status of the attachment.

      • Possible values:
        • "pending"
        • "uploaded"
        • "failed"
        • "deleted"
    • uploaded_at string optional

      The date and time at which the attachment finished uploading. Formatted as an ISO 8601 timestamp. Omitted if the attachment hasn't been uploaded yet.

      • Format: date-time
    • created_at string required

      The date and time at which the attachment was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments/0920582c7ff041399e34823a0be62549/complete' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "0920582c7ff041399e34823a0be62549",
    "filename": "debug-logs.tar.gz",
    "content_type": "application/gzip",
    "size_bytes": 1024000,
    "upload_status": "uploaded",
    "uploaded_at": "2024-10-20T10:15:00Z",
    "created_at": "2024-10-20T10:10:00Z"
  }
}
Live
Send a request to see the response.

Get attachment download URL

GET /api/v1/tickets/{ticket_id}/attachments/{attachment_id}/download

Generate a temporary download URL for an attachment.

Path Parameters

  • ticket_id string required

    The ticket ID.

  • attachment_id string required

    The attachment ID.

Response:200

  • data AttachmentDownloadResponse required

    The response with the download URL.

    • download_url string required

      A presigned URL for downloading the file.

    • expires_in integer required

      The URL expiration time in seconds.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
  • "global/object-does-not-exist"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/tickets/0920582c7ff041399e34823a0be62549/attachments/0920582c7ff041399e34823a0be62549/download' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "download_url": "https://s3.amazonaws.com/...presigned-download-url",
    "expires_in": 3600
  }
}
Live
Send a request to see the response.

Workspaces

List workspaces

GET /api/v1/workspaces

Lists the workspaces the requester is a member of, by default (when view=membership), or all workspaces in the account (when view=all). The view=all option requires the iam:workspace:read permission on the account.

Query Parameters

  • view enum optional
    • Default: "membership"
    • Possible values:
      • "membership"
      • "all"

Response:200

  • data array of Workspace required
    • Workspace

      A workspace provides logical isolation for resources within an account.

      • id string required

        The unique identifier (ID) of the workspace.

      • name string required

        The name of the workspace.

      • account_id string required

        The unique identifier of the account that owns this workspace.

      • created string required

        The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

        • Format: date-time
      • is_default boolean required

        Whether this is the default workspace for the account.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/workspaces' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "c4d291f47f9d436fa39f58493ce3b50d",
      "name": "My Workspace",
      "account_id": "a8d9c6729e12468786d1c44c0e942719",
      "created": "1970-01-01T00:00:00.000Z",
      "is_default": false
    }
  ]
}
Live
Send a request to see the response.

Create workspace

POST /api/v1/workspaces

Creates a workspace with the specified name and makes the requester a member.

Body Parameters

  • name string required

    The name of the workspace.

    • Minimum length: 1
    • Maximum length: 128

Response:200

  • data Workspace required

    A workspace provides logical isolation for resources within an account.

    • id string required

      The unique identifier (ID) of the workspace.

    • name string required

      The name of the workspace.

    • account_id string required

      The unique identifier of the account that owns this workspace.

    • created string required

      The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • is_default boolean required

      Whether this is the default workspace for the account.

Common Error Response Codes

400: Bad Request
  • "global/quota-exceeded"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/workspaces' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Workspace"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Workspace",
    "account_id": "a8d9c6729e12468786d1c44c0e942719",
    "created": "1970-01-01T00:00:00.000Z",
    "is_default": false
  }
}
Live
Send a request to see the response.

Retrieve workspace details

GET /api/v1/workspaces/{id}

Retrieves the details of a specific workspace.

Path Parameters

  • id string required

    The unique identifier (ID) of the workspace

Response:200

  • data Workspace required

    A workspace provides logical isolation for resources within an account.

    • id string required

      The unique identifier (ID) of the workspace.

    • name string required

      The name of the workspace.

    • account_id string required

      The unique identifier of the account that owns this workspace.

    • created string required

      The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • is_default boolean required

      Whether this is the default workspace for the account.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Workspace",
    "account_id": "a8d9c6729e12468786d1c44c0e942719",
    "created": "1970-01-01T00:00:00.000Z",
    "is_default": false
  }
}
Live
Send a request to see the response.

Update workspace

PATCH /api/v1/workspaces/{id}

Updates a workspace. This is a partial update that allows updating the name.

Path Parameters

  • id string required

    The unique identifier (ID) of the workspace

Body Parameters

  • name string optional

    The new name for the workspace. If not provided, the name will not be updated.

    • Minimum length: 1
    • Maximum length: 128

Response:200

  • data Workspace required

    A workspace provides logical isolation for resources within an account.

    • id string required

      The unique identifier (ID) of the workspace.

    • name string required

      The name of the workspace.

    • account_id string required

      The unique identifier of the account that owns this workspace.

    • created string required

      The date and time at which the workspace was created. Formatted as an ISO 8601 timestamp.

      • Format: date-time
    • is_default boolean required

      Whether this is the default workspace for the account.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request PATCH --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "name": "My Updated Workspace"
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "c4d291f47f9d436fa39f58493ce3b50d",
    "name": "My Workspace",
    "account_id": "a8d9c6729e12468786d1c44c0e942719",
    "created": "1970-01-01T00:00:00.000Z",
    "is_default": false
  }
}
Live
Send a request to see the response.

Delete workspace

DELETE /api/v1/workspaces/{id}

Deletes the workspace with the specified ID.

Path Parameters

  • id string required

    The unique identifier (ID) of the workspace

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "workspaces/workspace-in-use"
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.

List workspace memberships

GET /api/v1/workspaces/{workspace_id}/memberships

Retrieves a list of all memberships for a workspace.

Path Parameters

  • workspace_id string required

    The unique identifier (ID) of the workspace.

Response:200

  • data array of WorkspaceMembership required
    • WorkspaceMembership

      A workspace membership, keyed on its own ID so identities and groups can be referenced uniformly.

      • id string required
      • workspace_id string required
      • member_type enum required

        The kind of entity referenced by member_id.

        • Possible values:
          • "identity"
          • "group"
      • member_id string required

        The unique identifier of the identity or group that is a member of the workspace.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242/memberships' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": [
    {
      "id": "ddaedf1b7a0e41ac981711504493b242",
      "workspace_id": "ddaedf1b7a0e41ac981711504493b242",
      "member_type": "identity",
      "member_id": "ddaedf1b7a0e41ac981711504493b242"
    }
  ]
}
Live
Send a request to see the response.

Create workspace membership

POST /api/v1/workspaces/{workspace_id}/memberships

Adds an identity to a workspace.

Path Parameters

  • workspace_id string required

    The unique identifier (ID) of the workspace.

Body Parameters

  • member_type enum optional
    • Default: "identity"
    • Possible values:
      • "identity"
      • "group"
  • member_id string required
  • role_ids array of string optional

    Workspace roles to assign to the new member.

    When omitted, the built-in Workspace Member role is assigned. An empty list assigns no roles.

    • string

Response:200

  • data WorkspaceMembership required

    A workspace membership, keyed on its own ID so identities and groups can be referenced uniformly.

    • id string required
    • workspace_id string required
    • member_type enum required

      The kind of entity referenced by member_id.

      • Possible values:
        • "identity"
        • "group"
    • member_id string required

      The unique identifier of the identity or group that is a member of the workspace.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
  • "global/forbidden"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request POST --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242/memberships' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>' \
     --data '{
  "member_type": "identity",
  "member_id": "ddaedf1b7a0e41ac981711504493b242",
  "role_ids": [
    "ddaedf1b7a0e41ac981711504493b242"
  ]
}'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "workspace_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_type": "identity",
    "member_id": "ddaedf1b7a0e41ac981711504493b242"
  }
}
Live
Send a request to see the response.

Get workspace membership details

GET /api/v1/workspaces/{workspace_id}/memberships/{membership_id}

Retrieves the details of a specific workspace membership.

Path Parameters

  • workspace_id string required

    The unique identifier (ID) of the workspace.

  • membership_id string required

    The unique identifier (ID) of the membership.

Response:200

  • data WorkspaceMembership required

    A workspace membership, keyed on its own ID so identities and groups can be referenced uniformly.

    • id string required
    • workspace_id string required
    • member_type enum required

      The kind of entity referenced by member_id.

      • Possible values:
        • "identity"
        • "group"
    • member_id string required

      The unique identifier of the identity or group that is a member of the workspace.

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request GET --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242/memberships/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {
    "id": "ddaedf1b7a0e41ac981711504493b242",
    "workspace_id": "ddaedf1b7a0e41ac981711504493b242",
    "member_type": "identity",
    "member_id": "ddaedf1b7a0e41ac981711504493b242"
  }
}
Live
Send a request to see the response.

Delete workspace membership

DELETE /api/v1/workspaces/{workspace_id}/memberships/{membership_id}

Removes an identity or group from a workspace. Cascades to related workspace-scoped role assignments.

Path Parameters

  • workspace_id string required

    The unique identifier (ID) of the workspace.

  • membership_id string required

    The unique identifier (ID) of the membership.

Response:200

  • data EmptyResponse required

Common Error Response Codes

400: Bad Request
  • "global/invalid-parameters"
401: Unauthorized
  • "global/invalid-api-key"
403: Forbidden
  • "global/account-inactive"
404: Not Found
  • "global/not-found"
429: Too Many Requests
  • "global/rate-limited"
Parameters & Request sample

Request sample

curl --request DELETE --url 'https://cloud.lambda.ai/api/v1/workspaces/ddaedf1b7a0e41ac981711504493b242/memberships/ddaedf1b7a0e41ac981711504493b242' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <YOUR-API-KEY>'
Response
Sample

ResponseStatus: 200 OK

{
  "data": {}
}
Live
Send a request to see the response.