# Abyss

> Abyss is the execution layer for AI-built tools. A Creator publishes a Python project as a Widget; Abyss gives it an input form, a share link and a price per run, and runs it in the cloud. Your code can run any Widget it can see with the library `abysshub`, for JavaScript and Python, and an API Key. Runs are paid in Byssium, a prepayment for runs bought from Abyss and spent only on Abyss (100 Byssium is about $1).

This briefing is for coding agents writing an integration.

## Use `abysshub`

- JavaScript: `npm install abysshub` (Node 20+, Bun, Deno). Python: `pip install abysshub` (3.9+).
- The library reads the key from `ABYSS_API_KEY`. A person creates the key in their Cave. It acts as them and is paid from their Byssium wallet. Keep it on a server: never write it into code, never put it in a browser.

The one call is `abyss.run(widget, input)`. It presses the Widget, waits for the run to end however long it takes, and returns the succeeded run: `run.result` (the JSON the Widget wrote), `run.output_files`, and `run.save(dir)` to write them all. A refusal or a failed run raises `AbyssError`: branch on `error.code`, never on the message.

```javascript
// index.mjs
import Abyss from "abysshub";

const abyss = new Abyss();

const run = await abyss.run("widget_1666", { text: "Hello" });
console.log(run.result);
await run.save("output");
```

```python
from abysshub import Abyss

abyss = Abyss()

run = abyss.run("widget_1666", {"text": "Hello"})
print(run.result)
run.save("output")
```

A file Field takes `file("path")` for a local file, or an `https` URL. `maxPrice` (`max_price` in Python) caps what a run may cost.

## Read a Widget's page before you call it

Every public Widget has a markdown page, `https://abysshub.com/widgets/{id}.md`, with what it does, its Fields, its price and its code, ready to run. `{id}` is the Widget's number: `widget_1666` is https://abysshub.com/widgets/1666.md. Read it for any Widget you call.

## Make a Widget

To build a Widget, or port a function-shaped tool you already have (an n8n flow, a script, a notebook) onto Abyss, use the [`abyss-widget` skill](https://github.com/Abysshub/abysshub-sdk/tree/main/skills/abyss-widget). Install it with `npx skills add Abysshub/abysshub-sdk --skill abyss-widget -a claude-code` (`-a` names your agent).

## Links

- [A Widget, as markdown](https://abysshub.com/widgets/{id}.md): its Fields, price and code.
- [The Docs, as markdown](https://abysshub.com/docs.md): publishing a Widget, then calling Abyss from your code: files, what comes back, errors, long runs, spending safely, limits and the HTTP reference.
- The library's full reference: its README for [JavaScript](https://github.com/Abysshub/abysshub-sdk/tree/main/js#readme) and [Python](https://github.com/Abysshub/abysshub-sdk/tree/main/python#readme).
- [openapi.json](https://api.abysshub.com/v1/openapi.json): the HTTP contract, `/v1`, for any other language. Served without a key.
- [Call Abyss from your code](https://abysshub.com/docs#api): the same page as HTML. Each error code has an anchor there, `#<code>`.