# Send a piggyback command to a specific instance of service

`POST /devops/piggyback/{serviceName}/{instanceIndex}`

Send a piggyback command to a specific instance of service

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:

- `serviceName` (path, string, required) - Specified service target for the command execution
  Type: string
  
  enum: ["things","policies","connectivity"]

- `instanceIndex` (path, string, required) - The index of the current instance
  Type: string

- `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

```json
"{\n  \"type\": \"cleanup.sudo.responses:cleanupPersistence\",\n  \"status\": 200,\n  \"entityId\": \"thing:ditto:thing1\"\n}"
```

- 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/things/string' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE' \
  -H 'Content-Type: application/json' \
  --data-raw '"{\n  \"targetActorSelection\": \"/system/sharding/thing\",\n  \"headers\": {\n    \"aggregate\": false\n  },\n  \"piggybackCommand\": {\n    \"type\": \"cleanup.sudo.commands:cleanupPersistence\",\n    \"entityId\": \"ditto:thing1\"\n  }\n}"'
```

### JavaScript

```javascript
const response = await fetch('https://ditto.eclipseprojects.io/devops/piggyback/things/string', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    'Content-Type': 'application/json',
  },
  body: '"{\\n  \\"targetActorSelection\\": \\"/system/sharding/thing\\",\\n  \\"headers\\": {\\n    \\"aggregate\\": false\\n  },\\n  \\"piggybackCommand\\": {\\n    \\"type\\": \\"cleanup.sudo.commands:cleanupPersistence\\",\\n    \\"entityId\\": \\"ditto:thing1\\"\\n  }\\n}"',
});

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

### Python

```python
import requests

response = requests.post(
    'https://ditto.eclipseprojects.io/devops/piggyback/things/string',
    data='"{\\n  \\"targetActorSelection\\": \\"/system/sharding/thing\\",\\n  \\"headers\\": {\\n    \\"aggregate\\": false\\n  },\\n  \\"piggybackCommand\\": {\\n    \\"type\\": \\"cleanup.sudo.commands:cleanupPersistence\\",\\n    \\"entityId\\": \\"ditto:thing1\\"\\n  }\\n}"'.encode('utf-8'),
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```