---
title: "Using the Allspice API"
slug: "using-the-allspice-api"
description: "Get a rundown on why and how you can use the Allspice API here."
updated: 2026-10-23T18:34:32Z
published: 2026-10-23T18:34:32Z
canonical: "learn.allspice.io/using-the-allspice-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://learn.allspice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the AllSpice API

## Using the Allspice API

Allspice provides a robust API that allows you to interact programmatically with your repositories, manage your hardware projects, and automate various tasks. There are two primary ways to access the Allspice API:

1. **Preferred Method**: Using the `py-allspice` Python wrapper.
2. **Direct Method**: Using the REST API with Swagger interactive documentation.

This article will guide you through both approaches, including examples and links to further documentation.

---

## 1. Using the `py-allspice` Python Wrapper (Preferred)

The **py-allspice** Python wrapper simplifies interactions with the Allspice API by abstracting raw HTTP requests into easy-to-use Python methods. This is the preferred way to integrate Allspice's functionality into your workflows due to its ease of use, especially for Python developers.

### Key Resources:

- **Documentation**: The `py-allspice` documentation, built with pdoc, is available [here](https://allspiceio.github.io/py-allspice/allspice.html).
- **Examples**: Example Python scripts using the `py-allspice` wrapper are hosted in the [GitHub repository](https://github.com/AllspiceIO/py-allspice/tree/main/examples).

### Installing the `py-allspice` Wrapper

To get started, you can install the latest `py-allspice` wrapper via `pip`:

```
pip install py-allspice
```

### Authenticating with Allspice

You’ll need an [Allspice authentication token](/v1/docs/allspice-personal-access-tokens-pat) to interact with the API. You can pass the token when initializing the API client. By default, the client connects to `hub.allspice.io`, but if you're using a self-hosted instance, you can specify the URL.

```
from allspice import AllSpice

# For Allspice Hub
allspice_client = AllSpice(token_text="YOUR_API_TOKEN")

# For self-hosted instances
allspice_client = AllSpice(allspice_hub_url="https://your-allspice-instance.com", token_text="YOUR_API_TOKEN")
```

### Common Use Cases and Example Scripts

Below are a few common use cases when using the `py-allspice` wrapper, along with links to example scripts from the official Allspice GitHub repository.

#### 1. **Retrieving Repositories**

You can easily retrieve a list of repositories associated with your user account using the `get_repos` method:

```
# Retrieve repositories
repos = allspice_client.get_repos()
for repo in repos:
    print(repo['name'])
```

For more examples, check out the [generate netlist](https://github.com/AllspiceIO/py-allspice/blob/main/examples/generate_netlist/generate_netlist.py).

#### 2. **Creating a Pull Request**

Automate the process of opening pull requests through the API:

```
# Create a pull request
pull_request = allspice_client.create_pull_request(
    repo_owner="your-org",
    repo_name="your-repo",
    base_branch="main",
    head_branch="feature-branch",
    title="New Feature",
    body="This adds a new feature to the repository."
)
print(f"Created PR: {pull_request['html_url']}")
```

Refer to [working with DRs](https://github.com/AllspiceIO/py-allspice/tree/main/examples/working_with_drs) for more details.

#### 3. **Handling Issues**

Managing issues programmatically is also straightforward:

```
# Create a new issue
issue = allspice_client.create_issue(
    repo_owner="your-org",
    repo_name="your-repo",
    title="Bug report",
    body="There's a critical bug in the system."
)
print(f"Issue created: {issue['html_url']}")
```

---

## 2. Using the Allspice API with Swagger

For more direct or custom integrations, the Allspice API can be accessed via its RESTful interface. The Allspice Hub provides a **Swagger**-based interactive API documentation that allows you to test and explore the API endpoints without needing to write any code.

### Key Resource:

- **Swagger Interactive Documentation**: [Allspice API Swagger](https://hub.allspice.io/api/swagger)

### How to Use Swagger

Swagger offers a UI to interact with the Allspice API, making it easy to understand the available endpoints, the required parameters, and the responses.

1. **Navigate to the Swagger Documentation**: You can access the Swagger documentation at [https://hub.Allspice.io/api/swagger](https://hub.allspice.io/api/swagger).
2. **Authenticate with Your Token**: To interact with authenticated endpoints (e.g., creating pull requests, managing repositories), you'll need to pass your API token. Swagger allows you to input the token directly into the UI.
  - Click the "Authorize" button at the top of the Swagger page.
  - Enter your token in the `AuthorizationHeaderToken (apiKey)` field: `Value`
  - API tokens must be prepended with "token" followed by a space. Ex:  

`token d82634f0bd3fd21a473c24a2c7a439bfa5af5417`

![image.png](https://cdn.document360.io/3d44af5c-3f49-4ca5-b152-10836a885c13/Images/Documentation/image%2872%29.png)

1. **Explore Endpoints**: Use Swagger's interface to explore available API endpoints for repositories, pull requests, issues, and more. For each endpoint, you can see the necessary parameters and try requests directly within the UI.

### Example: Retrieving Repositories via Swagger

To retrieve a list of repositories:

- **Endpoint**: `GET /api/v1/repos`
- **Parameters**: None required.
- **Response**: A list of repositories in JSON format.

Once authenticated, simply click the "Try it out" button for the endpoint and execute the request.

### Example: Creating a Pull Request via Swagger

To create a pull request:

- **Endpoint**: `POST /api/v1/repos/{owner}/{repo}/pulls`
- **Parameters**:
  - `owner`: The owner of the repository.
  - `repo`: The repository name.
  - Request body containing the `base`, `head`, `title`, and `body` of the pull request.
- **Response**: The pull request details in JSON format.

Enter the required parameters, then click "Try it out" to execute the request and create the pull request.

### Custom Integrations Using Swagger

If you’re developing custom integrations with systems outside of Python or need advanced custom workflows, using the Allspice API via Swagger allows you to understand the underlying API and build on top of it with any technology that supports HTTP requests.

---

## Conclusion

Whether you're using the `py-allspice` Python wrapper for streamlined integration or interacting directly with the API via Swagger, Allspice provides flexible options for programmatic access to its features. The preferred method for most users is the Python wrapper, which simplifies API interactions and integrates seamlessly into Python-based workflows. For more advanced use cases or non-Python environments, the Swagger interface offers a direct and interactive way to explore the full API.

To get started with the `py-allspice` wrapper, explore the [documentation](https://allspiceio.github.io/py-allspice/allspice.html) and [example scripts](https://github.com/AllspiceIO/py-allspice/tree/main/examples). For direct API exploration, visit the [Allspice API Swagger](https://hub.allspice.io/api/swagger) and try out the endpoints to see what’s possible.

If you have any questions or need further support, don’t hesitate to reach out to the Allspice team or consult the interactive API documentation for detailed usage guidelines.