Portal

The portal at /portal is where an organisation in the private preview manages its access to the Falcon API. It is a small set of pages served from this site that talk to the portal service: a sign-in page, a dashboard with usage and keys, a sandbox for every public route, and a page for changing your password. Administrators have one more page, for organisations and users.

Falcon is in private preview. Self-serve API keys and accounts are paused. Preview access is granted by an administrator, who issues portal credentials tied to an organisation; nothing on the portal creates an account.

Signing in #

An administrator hands you a username and a one-time password. The first sign-in asks for a new password of at least twelve characters before it continues; the issued password is not valid a second time. After that, sign in with your own password at /portal. A session lasts for the browser tab: closing it signs you out, and the Sign out control in the header ends it earlier.

Repeated wrong attempts pause sign-in for a few minutes; the page says so rather than reporting a wrong password. If you forget your password, an administrator resets it and issues a new one-time password.

Keys #

The dashboard lists the API keys of your organisation with their label, prefix, creation date, last use and status. A key is created with a label naming where it will be used — a server, an environment, a colleague’s integration — and is shown once, in full, with a copy control; the portal keeps only its prefix, so store the key before leaving the page. An organisation holds at most eight keys.

Revoking a key takes effect on the next request; there is no undo, and a revoked key stays in the list with its revocation date. The curl recipes on the dashboard take the prefix of a selected key so that you can see which key a command is meant for; the full key goes in the FALCON_API_KEY variable on your own machine.

Usage #

The dashboard shows, per preview quota bucket — intention, spatial, complete and audio — the number of calls this UTC calendar month against the allowance of your organisation’s plan, as a bar. A bucket whose allowance is not yet fixed shows its count alone. Counters reset at the start of the next month; calls that fail validation or authentication are not counted. The same numbers are available to integrations from GET /v1/usage with a key.

Hosting #

The Hosting panel of the dashboard shows the tier your organisation runs on — Shared by default — with a status badge. From the shared tier it offers a request form: choose a dedicated tier, pick the models to host for a GPU tier, add notes and send. The panel then shows Requested with the date and a Cancel request control until an administrator approves it; once active it shows the tier, the activated date, the models hosted and the endpoints in use, among them the private Falcon API address that runs the in-process models privately for the requests sent to it. The tiers, prices, lead time and limits are on Dedicated hosting.

The Web hosting panel below it covers the Web Hosting add-on: request a site name (the panel shows the https://<site>.falconlab.app address as you type), then upload a zip of the static site; the panel shows the status, the last upload and, once an administrator has published it, the address. Web Hosting has the price, the zip requirements and the limits.

Hosting and web routes #

The dashboard’s API panel carries the session-token routes behind the Hosting and Web hosting panels. GET /v1/portal/hosting returns the tiers with their prices, the services a tier can host and the organisation’s current hosting record; POST /v1/portal/hosting/request sends tier, optional models and optional notes, answers 409 hosting_active while a dedicated tier is active, and DELETE on the same path cancels a pending request. GET /v1/portal/web returns the add-on with its price and the organisation’s site record, whose url is https://<site>.falconlab.app once the site is active; POST /v1/portal/web/request sends {site, notes?} and answers 400 bad_site with a reason for a name that breaks the rules or is reserved, 409 site_taken for a name another organisation holds, or 409 web_active while the organisation’s site is active (an administrator changes an active site); DELETE on the same path cancels a pending request. PUT /v1/portal/web/upload takes the zip as the raw body with Content-Type: application/zip and an x-file-name header; it answers 409 web_not_requested before a site is requested, 400 bad_content_type when the body is not sent as a zip, 413 upload_too_large above 25 MB, 400 bad_zip for an archive that does not open, and 400 no_index without an index.html. All take the fls_ session token, never a key, and none is offered in the sandbox.

Sandbox #

The sandbox sends a request to any public route with your session — no key needed — and shows the HTTP status, the response envelope and the equivalent curl command. Each route starts with a working example body that you can edit. The spatial route has two examples, one from a scene sketch and one from an image: choose or drop an image file and the sandbox encodes it as base64 into image_base64 when the request is sent. The move route sends a sketch and a goal to Waymark Extra and shows the trace, its steps and the summary; its GPU service scales to zero, so the first call after a quiet period can take one to two minutes. The intention example carries model: "lim"; lim-nano and elim are accepted too. For /v1/sound and /v1/speak the sandbox decodes wav_base64 into a player and a download link.

Sandbox calls count against your organisation’s quota exactly as a key would, and a route whose model has no hosted endpoint yet answers 503, as documented on Status & versioning.

Administration #

An administrator sees every organisation with its plan, its number of users and keys, and its usage per bucket, and can create an organisation, change its plan, create a user in it, reset a user’s password, disable or enable a user, delete a user, and delete an organisation. Creating or resetting a user shows the one-time password once, with a copy control; it is not stored and cannot be shown again. A disabled user cannot sign in; the organisation’s keys are unaffected. Deleting a user removes the account and ends its sessions; deleting an organisation removes its users, revokes its API keys and its dashboard, and keeps only the usage history. Both actions ask for a second click to confirm and cannot be undone. An administrator can also open any organisation’s dashboard and sandbox by choosing it at the top of the page.

The Hosting requests table lists every organisation that asked for a dedicated tier with the tier, the models, the notes and the date. Approve opens an editor for that organisation — the tier, a status, the hosted models and one https endpoint per service — and saving it sets the record the API routes the organisation’s Express Cue and GPU model calls by; Decline returns the organisation to the shared tier. The Hosting control in the organisations table opens the same editor for any organisation, to change a tier or an endpoint later or to cancel a tier for the end of the month. The Web hosting requests table works the same way for the Web Hosting add-on: Publish opens an editor with the status, the site, a custom domain, the address and the date published; Decline removes the request; the Web control in the organisations table opens the same editor for any organisation.

API usage guidelines #

These guidelines are the ones shown on the dashboard; the contract they summarise is on API conventions and Access.