# API Invocation

A common use case for Orchestra workflows is to be integrated into or invoked from an external application.  This can be done using the Workflow API. The Workflow API provides endpoints to list available workflows, execute workflows, track execution status, and more.

### Available APIs

1. [List available workflows](/arcee-orchestra/workflows/api-invocation/list-available-workflows-api.md)
2. [Workflow Execution](/arcee-orchestra/workflows/api-invocation/workflow-execution-api.md)
3. [Workflow Execution Steps](/arcee-orchestra/workflows/api-invocation/workflow-execution-steps-api.md)
4. [Execution History](/arcee-orchestra/workflows/api-invocation/execution-history-api.md)
5. [Workflow Diagram](/arcee-orchestra/workflows/api-invocation/workflow-diagram-api.md)

### Swagger Documentation

[Arcee Orchestra Swagger Documentation](https://arcee.portal.swaggerhub.com/orchestra/default/arcee-orchestra-v-1-0-0)

{% hint style="info" %}
Swagger provides an easy way to test and visualize APIs and their required syntax. Open the link above in a new tab, (if you only see a base url, toggle to SwaggerUI) and you'll be presented a list of the Orchestra APIs.
{% endhint %}

### Setting up an API Key

All API requests require authentication using a Bearer token. To generate an API key:

1. Go to Settings --> API Tokens --> Add API Token.
2. Provide a name and select "Get API Token".

<figure><img src="/files/qwfv0uIMElbhRYuWF56q" alt="" width="422"><figcaption><p>Add a New API Token</p></figcaption></figure>

3. Copy the generated API Key. You will not be able to view this again so ensure you store it somewhere secure. You will also be provided code examples for calling the APIs in Javascript and Python.

<figure><img src="/files/LsEz4BBxq5u5gWF3Ere4" alt="" width="375"><figcaption><p>Add New API Token</p></figcaption></figure>

### Core Functionality

Each API call will use the API Key generated with the steps above as well as the base url: `https://orchestra.arcee.ai/api/v1/workflow`.

### Error Handling

All APIs adhere to standard HTTP status codes:

* **200 OK** – Request successful
* **400 Bad Request** – Invalid input
* **401 Unauthorized** – Invalid or missing authentication
* **404 Not Found** – Resource not found
* **500 Internal Server Error** – Server-side error

Proper error handling should be implemented when interacting with the API to manage failures effectively.

### Security Best Practices

To ensure secure API interactions, follow these best practices:

* Store API tokens securely in environment variables or credential stores.
* Use HTTPS for all API requests to prevent data interception.
* Implement proper error handling to avoid exposing sensitive information in API responses.

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.arcee.ai/arcee-orchestra/workflows/api-invocation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.