# Replication targets

A replication target is your own storage the workspace's archived data is copied to; list the targets and how their latest copies went.

Ids: text.

- `GET /workspaces/{workspace_id}/replication-targets` [List replication targets](#list-replication-targets)

## ReplicationTarget object

A replication target is storage you own that the workspace's archived data is copied to, for the organizations it covers.

- `id` (string): The target's id.
- `target_type` (string): The kind of storage it is, such as s3, s3_compatible, azure_blob, azure_files, gcs or b2.
- `name` (string): The target's name.
- `description` (string or null): The target's description; null when it has none.
- `enabled` (boolean): Whether data is copied to the target.
- `scope` (Scope): Which organizations' data is copied to the target, all or selected. A target saved without organizations copies nothing and reads as selected with none.
- `config` (map of string): The target's storage settings by name, such as bucket, s3_region or azure_container. Settings that are not storage settings are left out, and so is an s3_endpoint carrying a user name or a query. Its contents are not part of the API contract and may change.
- `credential_names` (array of string): The names of the credentials stored on the target, such as s3_secret_access_key, in order. The credentials themselves are never sent.
- `job_status` (ReplicationJobStatus or null): How the target's latest run went; null until it has run.

## List replication targets

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/replication-targets`

Preview

Returns the workspace's replication targets you can see, in id order: where each copies data, its storage settings, which credentials it stores and how its latest run went. Needs `archive.config.read`: held over every organization, it lists every target; held at some organizations, it lists the targets that name one of them. A target's organizations are cut to those you can see. Credentials are named, never sent.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `archive.config.read`

Needs `archive.config.read`. `archive.config.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `target_type`, `name`, `description`, `enabled`, `scope`, `config`, `credential_names`, `job_status`

### Response (200)

- `replication_targets` (array of ReplicationTarget, required): Every one of the replication targets you can see.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `archive.config.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Example

List the replication targets

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/replication-targets" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "replication targets retrieved",
  "replication_targets": [
    {
      "id": "offsite-copy",
      "target_type": "s3",
      "name": "Offsite copy",
      "description": "Nightly copy to the MSP's own bucket",
      "enabled": true,
      "scope": {
        "kind": "all",
        "org_ids": [],
        "inherited": false,
        "other_orgs": false
      },
      "config": {
        "bucket": "northwind-archive",
        "s3_region": "us-east-2"
      },
      "credential_names": [
        "s3_access_key_id",
        "s3_secret_access_key"
      ],
      "job_status": null
    }
  ]
}
```

## Scope object

- `kind` (one of the values below, required): Which organizations. Required.
  - `all`: Every organization, those added later included.
  - `selected`: The organizations in `org_ids` and everything below them.
  - `workspace`: The workspace itself, no organization.
- `org_ids` (array of uuid): With selected, the topmost organizations you can see, sorted; empty otherwise. Every answer sends it. On a write, the organizations it covers: at least one with selected, none otherwise.
- `inherited` (boolean): True when one of `org_ids` sits below an organization the scope names that you cannot see. Read-only: every answer sends it, and a write ignores it.
- `other_orgs` (boolean): True when the scope covers organizations you cannot see, which are left out without an id or a count; with all, when you cannot see every organization. Read-only: every answer sends it, and a write ignores it.

## ReplicationJobStatus object

- `last_job_id` (string or null, required): The id of the latest run.
- `healthy` (boolean, required): Whether the latest run succeeded.
- `severity` (integer, required): How serious the latest run's outcome is, on the log severity scale: 9 ok, 13 warning, 17 error, 21 fatal.
- `status` (string, required): Where the latest run stands.
- `started_at` (date-time or null, required): When the latest run started.
- `finished_at` (date-time or null, required): When the latest run finished.

---

Source: <https://sparklogs.com/docs/api/reference/replication-targets>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
