# API basics

The stub Connect API is a RESTful API allows you to push income, sales, and expense data into a user's stub account. 

### Requests and responses

The majority of request in the stub Connect API are post request. The payloads you send are queued and processed asynchronously. Successfully queue payloads will 

```json
// Example response
{
    "error": false,
    "message": "Here's looking at you, kid."
}
```

If the request was unsuccessful or the malformed, `error` will be `true` with a reason, when available, contained in the `message`.

### Webhooks

When pushing data asynchronously into stub the result of push will be returned to the specified webhook URL when completed. For data pushes the webhook is optional.

When pulling data asynchronously from stub data will be returned to the specified webhook URL when ready. For data pull the webhook is mandatory. 

```json
// Example asynchronous request
{
  "apikey": "sk_test_xxxxxxx",
  "appid": "my-cool-app",
  "uid": "uuid-uuid-uuid",
  "webhook": "https://your.web.hook.com",
  "signature": "string" // an identifier to verify the response is from stub
}
```

### Retries

Webhooks will be retried 4 times using an exponential back-off algorithm in the following time intervals:

1. 10 seconds later
2. 2.5 minutes later
3. 30 minutes later
4. 6 hours later

After the fourth retry the data is discarded. 


---

# 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://developers.stub.africa/api-basics.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.