# Emit Event API

> Emit one or several events of API Maker over HTTP with the emit event system API - the event data reaches the listeners, and their outputs come back.

Source: https://docs.apimaker.dev/v4/docs/apis-all/system-apis/system-generated-emit-event-api.html

Emits an [event](https://docs.apimaker.dev/v4/docs/apis-all/events/user-created-events-api.html) of the account : its listeners run with the data, and the call answers what they returned.

| | |
|---|---|
| Method | POST |
| URL | `/api/system-api/admin/emit-event` : `admin` is the user path of your account |
| Body | `{ name, eventData?, executeListeners? }` or an array of them |
| Answer | `data` : the event with `outputArr`, one entry per listener |
| From code | [`g.sys.system.emitEvent`](https://docs.apimaker.dev/v4/docs/apis-all/system-apis/system-generated-emit-event-api.html#from-code) |

## The call

**Body**

```json
{ "name": "order-placed", "eventData": { "order_no": 1001 }, "executeListeners": [ "send-invoice" ] }
```

**Answer**

```json
{
    "success": true,
    "statusCode": 200,
    "data": { "name": "order-placed", "eventData": { "order_no": 1001 }, "executeListeners": [ "send-invoice" ], "outputArr": [ { "listenerName": "send-invoice", "output": { "notified": true } } ] }
}
```

**Body : several events**

```json
[
    { "name": "order-placed", "eventData": { "order_no": 1001 } },
    { "name": "stock-changed", "executeListeners": [ "sync-warehouse", "alert-low-stock" ] }
]
```

- `executeListeners` names the listeners to run ; absent, every listener of the event runs.
- A chain which comes back to an event already running is stopped : no infinite loop.

## From code

**TypeScript**

```typescript
const result = await g.sys.system.emitEvent('order-placed', { order_no: 1001 }, [ 'send-invoice' ]);
g.logger.log(result.outputArr);
```

**Python**

```python
result = await g.sys.system.emit_event('order-placed', {'order_no': 1001}, ['send-invoice'])
g.logger.log(result.output_arr)
```

**PHP**

```php
$result = $g->sys->system->emitEvent('order-placed', ['order_no' => 1001], ['send-invoice']);
$g->logger->log($result->outputArr);
```

**C#**

```csharp
var result = await g.Sys.System.EmitEvent("order-placed", new { order_no = 1001 }, ["send-invoice"]);
g.Logger.Log(result.OutputArr);
```

**Go**

```go
result, err := g.Sys.System.EmitEvent("order-placed", am.M{"order_no": 1001}, "send-invoice")
if err != nil {
	return nil, err
}
g.Logger.Log(result.OutputArr)
```

**Rust**

```rust
let result = g.sys.system.emit_event("order-placed", json!({ "order_no": 1001 }), &["send-invoice"])?;
g.logger.log(json!(result.output_arr));
```

**Java**

```java
EmittedEvent result = g.sys.system.emitEvent("order-placed", Map.of("order_no", 1001), List.of("send-invoice"));
g.logger.log(result.getOutputArr());
```

**Kotlin**

```kotlin
val result = g.sys.system.emitEvent("order-placed", mapOf("order_no" to 1001), listOf("send-invoice"))
g.logger.log(result.outputArr)
```

## Access and settings

- Over HTTP, a system API answers once its [settings](https://docs.apimaker.dev/v4/docs/settings/systemApiSettings.html) give it `apiAccessType: TOKEN_ACCESS` (the token of an API user whose [group](https://docs.apimaker.dev/v4/docs/apis-security/api-group-permission.html) grants this system API, in `x-am-authorization`) or `IS_PUBLIC`. Without settings it is `NO_ACCESS` : your code calls it through `g.sys`, the admin panel tests it, and an HTTP call is refused. The group must also grant the event.
- The settings can also cache the answer or require person tokens (`authProviders`) ; [pre and post hooks](https://docs.apimaker.dev/v4/docs/apis-all/hooks/preHook-api.html) run around it like around any API.
- The [request headers](https://docs.apimaker.dev/v4/docs/apis-all/header/requestHeader.html) apply : `x-am-response-case`, `x-am-content-type-response`, `x-am-internationalization`, `x-am-tenant-username`…

## Errors

| Code | When |
|---|---|
| `400` | The body is wrong : the message names the missing or invalid key. |
| `401` | No valid API user token, or the API is `NO_ACCESS` : `You are not authorized to access this API.` |
| `403` | No group grants this system API. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v4/docs/apis-all/overview.html) · [Response format](https://docs.apimaker.dev/v4/docs/apis-all/response-format.html) · [System API settings](https://docs.apimaker.dev/v4/docs/settings/systemApiSettings.html) · [System APIs from code](https://docs.apimaker.dev/v4/examples/sys/system/system.html)