Build with Idam
Describe an idea, follow implementation and review a private preview. Learn about saved conversations, voice, files, credits and the task API.
Last updated 2026-10-04
What you'll achieve
- Start a supported project from a build request and follow it to a private preview.
- Continue saved conversations with voice, files and workspace credits.
- Use task APIs and review a specific release before publication.
Idam turns a supported build request into a project, saved source and a checked private preview. You can also ask a brief question, plan a product or improve an existing project in the same conversation. Open Idam from your dashboard, or beside the editor. Your account needs Idam access and permission to work on the selected project.
From an idea to a running application
- Describe the result you want, such as “Build a flower-garden site with a gallery, seasonal highlights and contact details.” Choose an existing project under Options when you want to improve it.
- Review your request and credit limit, then choose Send. Idam detects the request type. A new build request creates a project with a supported starter and an editable name. Questions can be answered without creating a project. Choose Plan first when you want a proposal before implementation.
- Follow the conversation and execution steps as Idam inspects relevant context, saves source, builds and checks the private preview. Clear build requests authorize this work; questions and plans do not. Saved checkpoints preserve the changes, and eligible failures receive bounded automatic repair.
- Open the preview and try the important interactions. Ask for changes in the same conversation. Recorded checks cover specific scenarios; they do not establish that an external sign-in, payment, email or data service is configured. Idam explains unsupported requirements and any setup still needed.
- Review the concrete release details and choose Publish when ready. Confirm the live URL and keep the previous release available for rollback. Workspace roles and any project approval requirements still apply.
Use the browser IDE and source-control guide for editing and the build and release guide for delivery. Idam does not publish a proposal merely because you approved its plan.
Publication from a verified preview
After the current source passes private preview checks, Idam prepares the release automatically. Preparation copies the verified frontend into immutable release storage and includes the project's verified backend modules. It does not change the public site. A single production destination is selected automatically; projects with multiple production destinations require a choice.
The publication panel shows the project, destination and public address. Publish approves that specific source version and release configuration through the normal publication service. Model output and agent credentials cannot supply this approval. Changes to source, permissions or the selected destination invalidate an unstarted approval. Withdraw approval is available until publication starts.
The API is rooted at /api/idam/tasks/{task_id}/releases/. GET lists destinations and recent reviews; POST accepts exactly request_id (UUID), artifact_id (UUID) and environment_id (integer or null). Retrieve an individual review at {review_id}/. Approve with POST {review_id}/approve/ and the exact returned action_digest; withdraw with an empty POST {review_id}/revoke/. Clients retain the preparation request ID across connection loss and observe the existing review before retrying. Approval retries return the original publication operation without creating another release or refreshing authority.
Publication status distinguishes queued work, publication in progress, delivery propagation, active delivery, replacement by another release and removal under retention. Open site appears when the current release is active. A successful publication operation establishes control-plane completion; the separate delivery status establishes whether serving locations have acknowledged the release. Neither status proves every application feature works. Private preview checks cover homepage rendering and the recorded application scenarios on desktop and phone. Coverage remains limited to those checks; review untested features and external integrations before publication.
Automatic application checks
Build and design responses can include an acceptance array of named scenarios. These describe expected interactions; they are not evidence that anything ran. The control plane freezes the validated scenarios against the exact source revision, artifact digest and manifest digest before starting the isolated preview browser. Responses retained from before this contract keep their original homepage checks.
Each scenario begins with a relative page navigation and ends with a visible-content assertion. Supported steps are navigate, click, fill, press and check; targets use an exact accessible role and name. Selectors, scripts, external URLs and authority fields are rejected. Plans allow up to four scenarios, 2–10 steps per scenario, 24 steps combined and 16 KiB of JSON; synthetic form text is limited to 500 UTF-16 code units per fill.
The scheduler checks the homepage, then runs each scenario on desktop and phone and inspects the resulting page health. Every action retains one durable request identity. A lost reply is reconciled against its original receipt; it does not authorize another click. Customer takeover pauses new actions until control returns. Source changes invalidate the current check; cancellation, access loss and content removal prevent new success records.
execution.preview_checks.application_checks lists each scenario, screen, completion count and step evidence. A completed click does not pass its expected-result assertion. Missing receipts, invisible expected content, browser errors, blocked external requests and incomplete inspection cannot be reported as a pass. Publication preparation and approval revalidate all persisted checks for the current source. The browser stays isolated from external services, so a successful local form interaction does not establish that an email, payment or other external effect occurred.
Release preparation and approval also match the saved observations to the original browser operations. Each operation must belong to the same task, requester, source revision and artifact, match the frozen action request, and have an ordered, completed receipt whose metrics agree with the saved result. Missing or inconsistent evidence prevents publication; the UI presents those checks as incomplete. The same validator can establish a recorded negative observation for recovery decisions, but that observation alone does not grant permission to edit source, spend credits or repeat an action. Cancellation, current project access, source changes and execution authority are checked separately at each action boundary.
Project evidence includes bounded scenario status and receipt/frame digests without form inputs or generated scenario labels. Conversation content removal also clears the frozen plan, pending request and stored check details; operational receipt identities remain subject to their own retention rules.
Preview delivery verification
After application checks pass, a separate observer reads every artifact file and every planned navigation through the generated private preview origin over public HTTPS. Each response must match the expected bytes, content type and gateway security policy. execution.preview_verified becomes true only when these observations and the original application receipts both validate for the current source and access permissions. execution.preview_delivery exposes progress, the observation time and a bounded failure code. A source, permission or preview-domain change makes prior delivery evidence stale.
The observer uses a two-minute internal grant that cannot evict a customer's preview session. Credentials stay in memory and are revoked after each attempt. The worker checks public destinations, pins the validated address, verifies TLS and rejects redirects. Limits are 256 request targets, 16 MiB per response, 64 MiB in total and 80 seconds of network work per attempt. Exceeding a limit fails the whole observation. Four attempts are allowed within a 15-minute job lifetime; periodic recovery resumes lost registrations and queue deliveries without rebuilding or republishing the project.
Recovery after a failed build or preview
When automatic repair is enabled, a build request can include up to two repair attempts within its original credit limit and expiry. A repair continues the saved conversation, inspects source and creates another private build. It retains the original application checks. It cannot publish or write to an external connection. Requests admitted without repair permission do not gain it later.
Repair starts from recorded evidence: an authenticated build receipt paired with its ingestion event, or private browser receipts that establish a failed check. Eligible build failures are compiler exits 1 or 2 and missing build output. Installation failures, storage outages, timeouts and resource termination require diagnosis. Eligible preview failures include missing expected content, overflow, script errors and failed page resources. An exact control lookup that finds no match or multiple matches can also support repair when its receipt includes a fresh frame; the attempted action remains incomplete. Blocked external access, unknown action outcomes and checks without fresh evidence require diagnosis.
If the browser explicitly rejects a launch before admission because it has no capacity, polling can retry that same session within its original expiry and current permissions. An accepted launch, an uncertain send or a browser action is never replayed by this recovery.
An identical failure stops further automatic repair, even if operation IDs, source revisions or compiler exit codes change. Exhausted credits, expired authority, changed source or permissions, cancellation and conversation removal also stop new work. Lost callbacks recover the saved decision without repeating a completed provider operation. Task status exposes execution.repair; activity and saved conversation messages identify repair attempts and their stop reason. Draft text, voice notes and attachments stay in the composer while the conversation advances.
Share useful context
Describe the outcome, constraints and expected behavior. For a problem, include what you tried, what happened and what you expected. You can select up to eight saved project files, with a limit of 16 KiB per file and 24 KiB combined. Review their contents before authorizing sharing with Azure OpenAI. Never submit credentials.
Use Attach files from your device for documents, images, videos or ZIPs that are outside your project. Attach up to eight files: 10 MB each, or 50 MB for a video, with 100 MB combined. Extracted text is limited to 24 KiB and images or sampled video frames to eight per request. Videos can be up to three minutes; Idam samples frames and does not transcribe their audio. ZIPs can contain supported text, source files, documents and images. Review the prepared files before sharing them with Idam.
Use Record a voice note to record up to three minutes, watch the waveform and elapsed time, then transcribe. You can edit the transcript before adding it to your request. Transcription is charged by measured duration to six decimal places in credits, with the maximum shown before submission. Adding a transcript does not start a task. Recent transcripts and unused prepared files remain recoverable for 24 hours; original recordings are not saved.
Text, voice and files share one composer on the dashboard, in projects and in saved conversations. Add or discard a recorded note before sending. You can collapse attachment details while keeping the selected files. If an upload or transcription loses its response, use Check upload or Check transcript to retrieve the same receipt. This does not send another upload or transcription. Expired files must be removed before sending.
Switching accounts or workspaces clears the private draft. Hiding an embedded Idam panel stops its microphone and aborts in-flight media requests. Reopening the panel preserves typed text and lets you check an interrupted upload. Changing the destination project on the dashboard also stops the microphone; review the retained text and selected files before sending to that project.
The task starts with project information prepared when you submit it, selected source files and relevant conversation context. When project source inspection is enabled, Idam can read more relevant source during execution at the same saved revision. Each read checks current access, protects private and generated files, screens the whole file for secrets and returns a bounded excerpt with its file hash and coverage. Inspection appears in task activity. Unavailable or omitted source is reported explicitly. Later file edits stop the task from using stale evidence; they do not update it automatically. Saved project guidance carries your preferences into future tasks; it is not proof of the project's current state.
See Project evidence for source relationships, revision matching, coverage limits and the distinction between artifact and application verification.
See the Privacy Policy for AI processing, provider handling, international transfers and retention. Clearing guidance or removing task content does not recall content already processed or remove every related copy.
Return to previous work
Open Saved conversations on the Idam dashboard, or Your task history in a project, to return to submitted requests and replies. A question can start without a project. Asking Idam to build in that conversation creates a project and keeps the earlier messages. Dashboard history shows the latest accessible turn in each conversation; project history also keeps individual tasks. A follow-up becomes available when the previous task and its usage checks finish. Eligible interrupted tasks offer a resume action; check their status before starting replacement work. Removed content cannot be reopened.
An unsubmitted idea stays in the current tab and clears on refresh or workspace change. Submit the request before relying on task history to preserve it.
Understand credits
AI credits are pooled in your workspace. Idam reserves credits before work begins and settles model charges from measured tokens at the quoted model rates, rounded up to the nearest 0.000001 credit. Voice charges use measured duration with the same precision. Each task also includes a two-credit orchestration charge, and tool charges may apply. A small model call can cost a fraction of a credit; that is separate from the total task charge. Unused reservations are released after usage is confirmed. Cancelling a task does not make work already performed free.
Review the task limit before submitting. The composer defaults to 100 credits; Options lets you set a task limit from 1 to 2,000 credits. Check workspace billing for your allowance, balance and any funding or usage restrictions. Other resources, including builds and hosting, follow their own plan limits.
Task limits, plan grants and reservation ceilings remain whole credits. Wallet balances, confirmed usage and refunds retain fractional credits. Tasks and voice notes admitted before fractional metering keep their original whole-credit rounding, including on recovery. The precision change does not multiply existing balances or change approved plan allowances or rates.
Credit fields in retained events and internal analytics use JSON integers for whole values and six-place decimal strings for fractional values, for example 2 or "2.001001". Wallet and task API observations remain JSON numbers for compatibility; use a decimal-aware parser for accounting exports. Never calculate a new charge from a displayed balance or analytics event. The canonical ledger performs exact decimal arithmetic; provider-dollar costs are recorded separately.
Use the task API
Release status reads have a separate per-user limit of 120 requests per minute, so the three-second publication poll does not consume the allowance for starting AI tasks. Release preparation and approval share a 20-per-hour limit. Private preview creation and shared-browser creation each have their own 20-per-hour limit. Withdrawing a release approval, revoking private preview access and cancelling a pending browser start each have a separate 20-per-hour limit, so reaching a creation limit does not prevent stopping that operation. These limits do not replace authorization, credit checks or build capacity checks. A 429 response includes Retry-After; wait that many seconds before retrying the same operation.
For supported runtimes, available capabilities and fresh account facts, see the
versioned capability catalogue. Its authenticated knowledge
endpoint, GET /api/idam/knowledge/, works without creating a project or starting
an AI request. Include X-Organization-Id for the selected workspace.
The base URL is https://api.blinkhost.me/api/idam/. Calls require an authenticated BlinkHost account with access to Idam and the selected project. Browser integrations must use the normal session and CSRF flow. Approved CLI or workload integrations use their supported authentication flow; do not copy credentials into project source or documentation.
For workspace MCP configuration and the current research integration boundary, see Connections and current research.
Live-search allowance
GET /api/idam/live-search/allowance/ requires authentication and the current
X-Organization-Id workspace membership. It returns a private, non-cacheable
schema-1 snapshot with organization_id, scope=workspace_pool, plan_slug,
monthly_limit, used, remaining, resets_at, available, code,
transaction_limit, transactions_used, usage_pending and in_progress.
Query parameters are not accepted. The same snapshot appears in workspace
knowledge under usage.live_search. A displayed snapshot does not authorize a
search: admission rechecks the subscription and retained sends under a database
lock before the network request. Downgrades and exhaustion do not revoke saved
outputs or invalidate an already issued model tool contract; a denied call
returns a durable unavailable result without provider I/O or a customer charge.
Limits are Free 0, Dev Pro 20, Team 60, Agency Pro 200 and Agency Scale 500 per UTC
calendar month. The actual Foundry tool_usage.web_search.num_requests is counted
separately, with monthly headroom of four transactions per included search. Only
one search per workspace can be sending at once. Missing or invalid original
usage blocks additional searches, including after the month changes. Page reads
do not spend search transactions, and customer MCP permissions remain separate.
The transaction headroom is an admission control, not an absolute provider spend
cap: Foundry can execute multiple internal requests despite max_tool_calls=1.
An in-flight response can exceed the remaining headroom. Its full observed usage
is retained, and further searches are blocked. Customer AI tariffs are unchanged.
The examples below run in an authenticated BlinkHost browser session. Use your integration's authenticated request client outside that context.
For device uploads, first GET attachments/ or voice/ with
X-Organization-Id to check availability, limits and the current voice quote.
When upload_transport is raw, POST the binary file with
Content-Type: application/octet-stream and
Content-Disposition: attachment; filename*=UTF-8''ENCODED_FILENAME.
Use a new UUID as the attachment_id query parameter, or for voice use
transcription_id plus the quoted policy_sha256. Encode the filename using
RFC 5987 and send each parameter exactly once. Older servers accept multipart
with these metadata fields and one file field. Keep the original UUID after
a timeout and GET attachments/UUID/ or voice/UUID/ to recover the result;
do not start a replacement paid operation. DELETE the same detail URL to remove
an unused prepared file or saved transcript. Requests remain private to the
requesting account and workspace.
// Read-only: load the first page of your project task history.
const projectId = 'YOUR_PROJECT_UUID';
const response = await fetch(
`https://api.blinkhost.me/api/idam/tasks/?project_id=${encodeURIComponent(projectId)}`,
{ credentials: 'include', headers: { Accept: 'application/json' } },
);
if (!response.ok) throw new Error(`Task history failed (${response.status})`);
const { enabled, tasks, next_cursor } = await response.json();
Follow next_cursor with the same project and account to load older tasks. Treat it as an opaque value. If it expires, reload the first page.
| Operation | Method and path | Result |
|---|---|---|
| List your project tasks | GET tasks/?project_id=PROJECT_UUID |
enabled, tasks and next_cursor |
| List your workspace conversations | GET tasks/?organization_id=ORGANIZATION_ID |
Latest accessible turn per conversation and next_cursor |
| Read a task | GET tasks/TASK_UUID/ |
Current task, output and activity |
| Read task activity | GET tasks/TASK_UUID/events/?cursor=CURSOR |
Up to 200 ordered events, cursor, has_more, last_sequence, task_status, content_removed_at |
| Read its conversation | GET tasks/TASK_UUID/conversation/ |
Conversation history and continuation state |
| Start a task | POST tasks/ |
Accepted task, HTTP 202 |
| Request cancellation | POST tasks/TASK_UUID/cancel/ |
Current task state after cancellation request |
| Resume eligible work | POST tasks/TASK_UUID/resume/ |
Resume result subject to current eligibility |
For automatic admission, send mode: "auto" to POST tasks/. Omit
project_id and include X-Organization-Id to start in a workspace. Questions
use the maintained platform catalogue and authorized workspace facts without
creating a project or granting execution tools. An explicit build creates a
supported project within current entitlements. Project-free model calls need
their own configured workspace funding scope. They do not borrow another
project's authority or funding.
Use the accepted task's conversation endpoint for follow-ups. Each saved turn
includes its own nullable project_id; use that turn's scope when linking it.
Keep the same client_request_id when recovering an uncertain submission.
History cursors are bound to the requesting account, workspace and optional
project; a cursor from another scope cannot be reused.
For task activity, omit cursor for the first page and follow the returned
opaque cursor while has_more is true. Activity cursors belong to the task and
requesting account; every read checks current access. Pin X-Organization-Id
to the displayed workspace. Responses, including errors, must not be cached
persistently. A confirmed events_cursor_invalid response permits one fresh
read from the beginning; transient reconnects keep their existing cursor.
Merge events by sequence, reject conflicting identities and show missing
sequences explicitly. Clear history on access loss or content_removed_at.
The dashboard displays the latest 100 entries with earlier entries available,
limits automatic catchup to 50 pages per batch, and pauses on repeated pages
or errors. Closing a panel cancels its reader. Task settlement triggers one
final refresh even when it races an earlier request; terminal tasks do not
keep polling. Activity describes recorded steps, not proof of a live release.
For contextual help from a project, IDE or error screen, include an optional
entry_context on the initial task request:
{
"surface": "deployment",
"project_id": "YOUR_PROJECT_UUID",
"organization_id": 42,
"reference": {"kind": "deployment", "id": "123"}
}
surface accepts project, deployment, backend, ide or preview.
reference is optional. Deployment references use decimal string IDs;
module_build references use build UUIDs on the backend surface, and
ide_preview references use report UUIDs on the preview surface. Both scope
fields must match the admitted project and workspace. Unknown fields, raw logs,
URLs and approval claims are rejected. The server reads the exact selected
record under current permissions. An IDE preview report identifies a customer
interface issue; it does not verify a cause or include unsaved editor source.
The detail response includes a safe entry_context summary. Keep the original
request and ID on an uncertain retry: it retains the admitted evidence snapshot.
A conversation follow-up refreshes the selected record under current access.
Pin requests to the selected workspace with X-Organization-Id, clear pending
context and attachments on account/workspace changes, and check the accepted
response's scope and reference before opening its task.
To start a plan, submit this JSON using your authenticated client and its CSRF protection where applicable:
{
"project_id": "YOUR_PROJECT_UUID",
"client_request_id": "A_NEW_REQUEST_UUID",
"prompt": "Plan a booking site with services and appointment requests.",
"mode": "plan",
"model": "gpt-6-luna",
"maximum_units": 100
}
Submitting this request can consume credits. Generate client_request_id once for each intended task, retain it and reuse it with the identical payload if a response is lost. Changing the ID creates a new operation. Inspect task history after an uncertain result before submitting more work. HTTP 202 means accepted; follow the task until its terminal state before treating it as complete.
maximum_units is an integer credit ceiling from 1 to 2000, not a token count or a promised charge. A request whose reservation exceeds its ceiling is rejected. Model access, budgets and project permissions remain enforced server-side. Source sharing is optional through source_paths; provide only the saved paths the user has reviewed and authorized.
An implementation request authorizes saving supported source changes and building a private preview within its scope. A plan requires a subsequent implementation request or source review before changes are applied. Public publication requires a separate approval tied to the current project, source and release configuration. Use the dashboard review flow for that approval. The /internal/ endpoints are worker infrastructure and are not customer APIs.
Resolve common interruptions
| What you see | What to do |
|---|---|
| Idam unavailable for the account | Confirm workspace access with an administrator. Existing manual project tools remain available. |
| Insufficient credits or budget | Check the workspace balance and task ceiling before retrying. |
| Sign-in or permission error | Renew your session and confirm the project and workspace role. |
| HTTP 429 | Wait before retrying and respect Retry-After when provided. Reuse the request ID for the same operation. |
| HTTP 409 or changed project state | Read the returned error code and current task. Refresh the review before approving changed source. |
| Build or preview failure | Follow any automatic repair already in progress. If it stops, use the retained diagnostics and conversation to address the reported cause without restarting completed work. |
| Request times out | Inspect history and status first; the server may already have accepted the task. |
For support, provide the project ID, task ID, error code and UTC time. Keep credentials and private source out of support messages unless a secure sharing route is agreed.
Help improve this page
Sign in to send page-specific feedback. For account-specific help, email support@blinkhost.me.