# Send a piggyback command

`POST /devops/piggyback`

Send a piggyback command to Pekko’s pub-sub-mediator

Authentication (security requirement alternatives):

```json
[
  {
    "DevOpsBasic": []
  },
  {
    "DevOpsBearer": []
  }
]
```

- DevOpsBasic: http (basic). Eclipse Ditto devops user (devops) + password (foobar)
- DevOpsBearer: http (bearer). A JSON Web Token issued by a supported OAuth 2.0 Identity Provider for the Eclipse Ditto devops user.

Parameters:

- `timeout` (query, string, optional) - Defines how long the backend should wait for completion of the request, e.g. applied when waiting for requested
acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or
together with `s`, `ms` or `m` unit. Example: `42s`, `1m`.

The default (if omitted) and maximum timeout is `60s`. A value of `0` applies fire and forget semantics for
the command resulting in setting `response-required=false`.
  Type: string

Request body: application/json (required)

Fields to send a command

Type: BasePiggybackCommandRequestSchema

Schema: [BasePiggybackCommandRequestSchema](https://sourcey-ditto.pages.dev/http-api-doc/models/basepiggybackcommandrequestschema.md)

- `targetActorSelection` (optional)
  Type: string

- `headers` (optional)
  Type: object
  
  - `aggregate` (optional)
    Type: boolean
    
    default: false
  
  - `is-group-topic` (optional)
    Type: boolean
    
    default: true

- `piggybackCommand` (optional)
  Type: object
  
  - `type` (optional)
    Type: string

Responses:

- 200: Response of command

Content type: application/json

Type: PiggybackManagingBackgroundCleanup

Schema: [PiggybackManagingBackgroundCleanup](https://sourcey-ditto.pages.dev/http-api-doc/models/piggybackmanagingbackgroundcleanup.md)

- `targetActorSelection` (optional)
  Type: string

- `headers` (optional)
  Type: object
  
  - `aggregate` (optional)
    Type: boolean
    
    default: false
  
  - `is-group-topic` (optional)
    Type: boolean
    
    default: true

- `piggybackCommand` (optional)
  Type: object
  
  - `type` (optional)
    Type: string

- 400: The request could not be completed. At least one of the defined query parameters was invalid.

Content type: application/json

Type: AdvancedError

Schema: [AdvancedError](https://sourcey-ditto.pages.dev/http-api-doc/models/advancederror.md)

- `status` (required)
  Type: integer
  
  The HTTP status of the error

- `error` (required)
  Type: string
  
  The error code of the occurred exception

- `message` (required)
  Type: string
  
  The message of the error - what went wrong

- `description` (optional)
  Type: string
  
  A description how to fix the error or more details

- `href` (optional)
  Type: string
  
  A link to further information about the error and how to fix it

- 401: The request could not be completed due to missing authentication.

Content type: text/plain

Type: TextUnauthorizeError

Schema: [TextUnauthorizeError](https://sourcey-ditto.pages.dev/http-api-doc/models/textunauthorizeerror.md)

Example:

```json
"The supplied authentication is invalid"
```

## Examples

### cURL

```bash
curl -X POST 'https://ditto.eclipseprojects.io/devops/piggyback' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/json' \
  --data-raw '"{\n  \"targetActorSelection\": \"/system/distributedPubSubMediator\",\n  \"headers\": {\n    \"aggregate\": false\n  },\n  \"piggybackCommand\": {\n    \"type\": \"namespaces.commands:blockNamespace\",\n    \"namespace\": \"namespaceToBlock\"\n  }\n}"'
```

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/devops/piggyback', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    'Content-Type': 'application/json',
  },
  body: '"{\\n  \\"targetActorSelection\\": \\"/system/distributedPubSubMediator\\",\\n  \\"headers\\": {\\n    \\"aggregate\\": false\\n  },\\n  \\"piggybackCommand\\": {\\n    \\"type\\": \\"namespaces.commands:blockNamespace\\",\\n    \\"namespace\\": \\"namespaceToBlock\\"\\n  }\\n}"',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://ditto.eclipseprojects.io/devops/piggyback',
    data='"{\\n  \\"targetActorSelection\\": \\"/system/distributedPubSubMediator\\",\\n  \\"headers\\": {\\n    \\"aggregate\\": false\\n  },\\n  \\"piggybackCommand\\": {\\n    \\"type\\": \\"namespaces.commands:blockNamespace\\",\\n    \\"namespace\\": \\"namespaceToBlock\\"\\n  }\\n}"'.encode('utf-8'),
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```