# Edit pending source files

Apply complete file replacements and deletions to working files. Keep staging unchanged. Do not commit or deploy.

## Endpoint

POST `/v1/spaces/{spaceId}/source/workspaces/{workspaceId}/files`

## Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

### Scopes:
- `spaces:write`
- `spaces:read`

## Path parameters

- `spaceId` string required
- `workspaceId` string required

## Request body

required `application/json`

- `expectedRevision` integer required  
Revision from the last workspace response. Read the workspace again after a revision conflict.

min: 0 · max: 9007199254740991

- `operationId` string required  
Unique ID for this operation. Reuse this ID and the same input after an uncertain response.

min length: 1 · max length: 128

- `operations` object[] required

Array of object  
  One of:
  - **object**
    - `action` string required
    - `path` string required  
      min length: 1 · max length: 4096
    - `contents` string required  
      Complete file contents. Omitted files do not change.
      max length: 1048576
    - `encoding` string  
      Allowed: `utf8`, `base64`, `hex`

## Responses

### 200 Response for status 200

- `$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

- `data` object required

- `workspace` object required
    - `id` string required
    - `spaceId` string required
    - `repositoryId` string required
    - `targetBranch` string required
    - `name` string required
    - `revision` integer required  
      min: 0 · max: 9007199254740991
    - `state` string required  
      Allowed: `initializing`, `active`, `conflicted`, `closed`
    - `baseCommitSha` string | any required
    - `indexCommitSha` string | any required
    - `workingCommitSha` string | any required
    - `headCommitSha` string | any required
    - `originalUploadVersionId` string | any required
    - `hasStagedChanges` boolean required
    - `hasUnstagedChanges` boolean required
    - `hasPendingChanges` boolean required
    - `needsSync` boolean required
    - `pendingOperationId` string | any required
    - `autoDeploy` boolean required
    - `createdAt` string required
    - `updatedAt` string required

- `commit` object  
    - `sourceCommitSha` string required
    - `parentSourceCommitSha` string required
    - `message` string required
    - `autoDeploy` boolean required

- `conflicts` object  
    - `phase` string required  
      Allowed: `staged`, `working`, `undo`
    - `labels` object required  
      - `ours` string required
      - `theirs` string required
    - `files` object[] required  
      Array of object
      - `path` string required
      - `result` string required
      - `base` object required  
        - `sourceCommitSha` string required
        - `content` string | any required  
        - `exists` boolean required
        - `binary` boolean required
        - `truncated` boolean required
      - `ours` object required  
        - `sourceCommitSha` string required
        - `content` string | any required
        - `exists` boolean required
        - `binary` boolean required
        - `truncated` boolean required
      - `theirs` object required  
        - `sourceCommitSha` string required
        - `content` string | any required
        - `exists` boolean required
        - `binary` boolean required
        - `truncated` boolean required

### Default Problem details (RFC 9457)  
Any 4xx/5xx response is one `application/problem+json` document.
- `$schema` string <uri>
- `type` string required
- `title` string required
- `status` integer required
- `detail` string required
- `code` string required
- `pointer` string
- `details` object
- `suggestions` string[]
- `next` string[]
- `requestId` string required

## Try it

### Server

Base URL https://api.spacefast.com

### Parameters
- `spaceId` path*
- `workspaceId` path*

## Request body

### Example cURL request
```shell
curl -X POST "https://api.spacefast.com/v1/spaces/string/source/workspaces/string/files" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "expectedRevision": 9007199254740991,\n  "operationId": "string",\n  "operations": [\n    {\n      "action": "upsert",\n      "path": "string",\n      "contents": "string",\n      "encoding": "utf8"\n    }\n  ]\n}'
```

### JavaScript fetch request
```javascript
const response = await fetch("https://api.spacefast.com/v1/spaces/string/source/workspaces/string/files", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"expectedRevision\": 9007199254740991,\n  \"operationId\": \"string\",\n  \"operations\": [\n    {\n      \"action\": \"upsert\",\n      \"path\": \"string\",\n      \"contents\": \"string\",\n      \"encoding\": \"utf8\"\n    }\n  ]\n}"
});
```

### Python requests example
```python
import requests

response = requests.post(
    "https://api.spacefast.com/v1/spaces/string/source/workspaces/string/files",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"expectedRevision\": 9007199254740991,\n  \"operationId\": \"string\",\n  \"operations\": [\n    {\n      \"action\": \"upsert\",\n      \"path\": \"string\",\n      \"contents\": \"string\",\n      \"encoding\": \"utf8\"\n    }\n  ]\n}",
)
```

### Response 200 default example
```json
{
  "$schema": "http://example.com",
  "data": {
    "workspace": {
      "id": "string",
      "spaceId": "string",
      "repositoryId": "string",
      "targetBranch": "string",
      "name": "string",
      "revision": 9007199254740991,
      "state": "initializing",
      "baseCommitSha": "string",
      "indexCommitSha": "string",
      "workingCommitSha": "string",
      "headCommitSha": "string",
      "originalUploadVersionId": "string",
      "hasStagedChanges": true,
      "hasUnstagedChanges": true,
      "hasPendingChanges": true,
      "needsSync": true,
      "pendingOperationId": "string",
      "autoDeploy": true,
      "createdAt": "string",
      "updatedAt": "string"
    },
    "commit": {
      "sourceCommitSha": "string",
      "parentSourceCommitSha": "string",
      "message": "string",
      "autoDeploy": true
    },
    "conflicts": {
      "phase": "staged",
      "labels": {
        "ours": "string",
        "theirs": "string"
      },
      "files": [
        {
          "path": "string",
          "result": "string",
          "base": {
            "sourceCommitSha": "string",
            "content": "string",
            "exists": true,
            "binary": true,
            "truncated": true
          },
          "ours": {
            "sourceCommitSha": "string",
            "content": "string",
            "exists": true,
            "binary": true,
            "truncated": true
          },
          "theirs": {
            "sourceCommitSha": "string",
            "content": "string",
            "exists": true,
            "binary": true,
            "truncated": true
          }
        }
      ]
    }
  }
}
```

### Error response example
```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```