Model APIs

Library access follows the caller's personal or organization scope. To give someone access without an account, create a share link with a deadline, keep the returned URL, and revoke the link when it is no longer needed.

There is no per-file ACL on the storage object itself; access is the Library scope plus share links.

How access works #

The 302 is the resolver response, not the media body. Follow its Location to fetch the bytes.

Library scope #

Personal assets belong to your personal Library. In organization context, teammates can read the shared Library, while the asset's user_id continues to name its creator. Choose the active context with PUT /me/active-organization; organization API keys stay bound to their organization. See Teams and organizations for switching context and roles.

Share links #

Create a link #

Set ASSET_ID to a ready asset you are allowed to share. These request examples use a seven-day lifetime. The CLI currently has no share command; its tab uses curl with the same NOLGIA_TOKEN credential.

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/assets/$ASSET_ID/share" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" -d '{"expires_in_days":7}'

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/assets/$ASSET_ID/share" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" -d '{"expires_in_days":7}'

import { createNolgiaClient } from "@nolgia/sdk";

const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!);
const { data: link, error } = await nolgia.POST("/assets/{id}/share", {
  params: { path: { id: process.env.ASSET_ID! } },
  body: { expires_in_days: 7 },
});
if (error) throw new Error(`${error.title}: ${error.detail ?? ""}`);
console.log(link.id, link.url);

import os
from uuid import UUID
from nolgia import AuthenticatedClient
from nolgia.api.sharing import create_asset_share_link
from nolgia.models import CreateShareLinkRequest, ShareLink

client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token=os.environ["NOLGIA_TOKEN"])
link = create_asset_share_link.sync(
    UUID(os.environ["ASSET_ID"]), client=client,
    body=CreateShareLinkRequest(expires_in_days=7),
)
if not isinstance(link, ShareLink):
    raise SystemExit(f"refused: {link}")
print(link.id, link.url)

use nolgia_client::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new("https://api.nolgia.ai/v1")
        .bearer_token(std::env::var("NOLGIA_TOKEN")?)
        .build()?;
    let id = std::env::var("ASSET_ID")?.parse::<uuid::Uuid>()?;
    let link = client.create_asset_share_link().id(id)
        .body_map(|b| b.expires_in_days(7_u64))
        .send().await?.into_inner();
    println!("{} {:?}", link.id, link.url);
    Ok(())
}

This is the production create response from share-create.json; the token and the URL's token are redacted. The SDK snippets are examples, not separate live captures.

{
  "access_count": 0,
  "created_at": "2026-09-21T03:33:52.874514Z",
  "created_by": "dad27b53-a85b-4e3d-8fd6-b152c803a27c",
  "expires_at": "2026-09-28T03:33:52.873377Z",
  "id": "26d786f5-437c-4da4-9f04-60342191299b",
  "kind": "asset",
  "target_id": "f7bc037c-d7d7-434a-8843-26675574de0d",
  "token": "…",
  "token_prefix": "EJIkUdv1",
  "url": "https://nolgia.ai/s/…"
}

List active links #

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/assets/$ASSET_ID/share" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

{
  "links": [
    {
      "access_count": 1,
      "created_at": "2026-09-21T03:33:52.874514Z",
      "created_by": "dad27b53-a85b-4e3d-8fd6-b152c803a27c",
      "expires_at": "2026-09-28T03:33:52.873377Z",
      "id": "26d786f5-437c-4da4-9f04-60342191299b",
      "kind": "asset",
      "last_accessed_at": "2026-09-21T03:33:53.01188Z",
      "target_id": "f7bc037c-d7d7-434a-8843-26675574de0d",
      "token_prefix": "EJIkUdv1"
    }
  ]
}

Resolve the media #

Set SHARE_TOKEN to the token returned at creation. This command shows the resolver response without following it; add -L to fetch the media.

$ curl -sS -D - -o /dev/null "https://api.nolgia.ai/v1/share/$SHARE_TOKEN"

These are the real response headers from share-resolve.headers; location is truncated.

HTTP/2 302
access-control-allow-headers: Authorization, Content-Type, X-Request-Id, If-Match, Idempotency-Key
access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
access-control-allow-origin: *
cache-control: no-store
content-type: text/html; charset=utf-8
location: https://storage.googleapis.com/nolgia-generations-prod/dad27b53-a85b-4e…
x-cloud-trace-context: 978e41fdddedef4cd8db4b39631ad0cd
date: Mon, 21 Sep 2026 03:33:53 GMT
server: Google Frontend
content-length: 941
via: 1.1 google
alt-svc: h3=":443"; ma=2592000

A valid share URL can outlast many media URLs. Keep the share URL and resolve it when needed; do not persist the Location as a replacement for the share link.

Revoke a link #

The path parameter is named token, but the captured revoke used the link id 26d786f5-437c-4da4-9f04-60342191299b and returned 204. Use your own listing's id as SHARE_LINK_ID.

$ curl --fail-with-body -sS -X DELETE \
  "https://api.nolgia.ai/v1/assets/$ASSET_ID/share/$SHARE_LINK_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

HTTP/2 204

There is no JSON body. The same public resolver request now returns the real problem captured in share-gone.json:

$ curl -sS "https://api.nolgia.ai/v1/share/$SHARE_TOKEN"

{
  "detail": "this share link has been revoked",
  "request_id": "localhost/7bnUUXx7b2-007297",
  "status": 410,
  "title": "Gone",
  "type": "about:blank"
}

Revocation stops future resolutions. A previously issued signed media URL has its own short expiry; revoking the share does not change that URL's signature.

Preview metadata and renders #

GET /share/{token}/meta returns the title, modality, media URL and expiry for a preview page or embed, with an optional description, thumbnail, duration and size. It has the same unknown/revoked/rate-limit behavior as the resolver, but does not increment the link's access count.

Renders use the same create, list and revoke pattern under /renders/{id}/share and /renders/{id}/share/{token}. Their visibility follows the composition's Library scope. Both kinds resolve through the same public /share/{token} and /share/{token}/meta routes.