Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.
Goal
Prepare a personal or team AI project without creating a Cloud application or making a model request.Prerequisites
- Access to the internal AI preview. These endpoints are not publicly available.
- A human session or personal token with explicit ai:read or ai:manage scope. A wildcard token alone is insufficient.
- For a team project, current team owner or admin authority. Funding changes require the current owner who pays.
Workflow
1
POST /api/v1/ai/projects with {“name”:“My AI project”}. Add team_id to create a team project. The response includes independent development and production environments, a zero monthly managed-credit ceiling and your allowed_actions.
2
To share project access, PUT /api/v1/ai/projects/{projectID}/grants/{userID} with role developer or viewer. For team projects, the person must remain a current team member; team membership alone does not grant project access. Personal project owners can grant access to an existing user.
3
Choose funding separately for each environment and provider. PUT /api/v1/ai/projects/{projectID}/environments/{environmentID}/bindings/{provider} with mode managed and your payer_id to authorize your existing AI credit account. Providers are anthropic and openai.
4
For BYOK, first PUT /api/v1/ai/projects/{projectID}/credentials/{provider} with key. Store the returned revision, then explicitly authorize a byok binding with payer_id and credential_revision. A stored key has not been verified with the provider.
5
For managed funding, PUT /api/v1/ai/projects/{projectID}/budget with monthly_microcredits. Optionally set a lower environment budget at /environments/{environmentID}/budget. One credit equals 1,000,000 microcredits. Keep the ceiling at zero until spending is authorized.
6
POST /api/v1/ai/projects/{projectID}/service-identities with name and environment_id. Then POST /keys with name, environment_id, service_identity_id and scopes [“ai:identity”]. Save the returned secret once in your server-side secret store.
7
Call GET /api/v1/ai/identity using the application key as a bearer token. The response identifies the project, environment and service identity. It confirms identity only; no model or provider call is performed.
8
To rotate, create and install a replacement key, then explicitly DELETE /api/v1/ai/projects/{projectID}/keys/{keyID}. To stop a project, POST its /archive endpoint. Restoring with /restore requires issuing new keys.
Funding and monthly limits
Managed reservations share the existing AI credit account. Account availability, the project ceiling and any lower environment ceiling must all permit admission. Outstanding reservations count against the UTC calendar month in which they were admitted; completion in another month stays attributed to the original month. Lowering a ceiling blocks new admissions without rewriting existing commitments. BYOK charges the payer’s provider account. Managed-credit ceilings do not cap provider-account spending, including activity outside Stackshift. GET /financial-summary returns only this project’s managed commitments, settled microcredits and BYOK reservation count. Viewers cannot read this financial summary or account-wide balances. No public reserve, settle or release endpoint exists.Identity, history and pagination
Application keys represent a project-owned service identity and cannot administer funding, grants or other Stackshift products. The creator is recorded separately; removing the creator from the team does not revoke the application identity. Keys expire after 90 days by default. An explicit expiry must be in the future and at most 365 days away. The only supported application scope in this phase is ai:identity; there is no wildcard default. Project, grant, identity, key and activity lists accept limit from 1 to 100 and an after UUID. Pass next_cursor as after for the next page. Ordering is by UUID, not event time. Empty lists return data: []. Responses carry request_id and X-Request-ID. Failures include a stable code and message. Use GET /activity to inspect successful administrative actions. Archive preserves this history; permanent deletion and workspace transfer are unavailable.Expected result
An independently scoped project and application key exist. Provider funding is explicit, credentials remain secret and project activity is inspectable. Inference is not available in this phase.