Request

A session does not push to the repository directly. The session's work is saved as a commit in a checkpoint, and to send that commit to the repository you create a push request. The platform (API) pushes only after a person with sessions:approve approves it. Requesting needs sessions:write.

Prepare a session that changes filesCopy Anchor Link

The SDK examples use the werft client made in Install the SDK, and the HTTP API examples use the shell variables API (the server address) and KEY (the key). This script appends a line to the repository's README.md, and the turn ends once you allow the permission request. Allowing it with the key that created the session works only with the development server's operator key. With a key issued in the web console, allow it from a client made with another key (A separate key for approvals).

import { waitForTurn } from "@werft-ai/sdk";

const note = await werft.sessions.create({
  profile_id: "claude-coding-local",
  repository_id: "sample-app",
  message:
    'GATE-SPEC {"id":"note","steps":[{"tool":"Bash","input":{"command":"echo tested | tee -a README.md","description":"append to README.md"}}],"final":"updated README.md"}',
});
const sessionId = note.session_id;
await waitForTurn(werft, sessionId, note.turn_id, {
  onRequest: { permission: () => ({ action: "allow" }) },
});

RequestCopy Anchor Link

The SDK passes only the session id, and the HTTP API by default sends an empty JSON object ({}) as the request body. The requester does not choose what is sent. The platform pins the session's latest checkpoint and its commit at that moment, and the branch agent/<session-id>. If you omit repository_id, the repository is the one named when the session was created. To send a repository that an agent session, which starts without one, attached, put its repository_id in the HTTP API body (the SDK's pushRequests.create does not take it yet). One request sends one repository, so with several repositories you make one request per repository, and the approval rule is the same for every repository.

const push = await werft.sessions.pushRequests.create(sessionId);
console.log({
  state: push.state,
  repository_id: push.repository_id,
  checkpoint_revision: push.checkpoint_revision,
  target_branch: push.target_branch,
});

{
  state: 'requested',
  repository_id: 'sample-app',
  checkpoint_revision: 0,
  target_branch: 'agent/…'
}

The response is 201. Use pushRequests.list (GET /v1/sessions/{id}/push-requests) for the session's list of requests and pushRequests.get (GET …/push-requests/{push_request_id}) for one request.

Next stepsCopy Anchor Link

• Approve: check the pinned commit and approve
• Reject