### Install Dependencies and Start Server

Source: https://github.com/beeminder/apidocs/blob/master/README.md

Installs project dependencies using Bundler and starts the Middleman development server for local documentation viewing. This is the primary method for local development.

```shell
bundle install
bundle exec middleman server
```

--------------------------------

### Start Server with Vagrant

Source: https://github.com/beeminder/apidocs/blob/master/README.md

Initializes and starts the Beeminder API documentation environment using Vagrant. This is an alternative to local setup, providing a consistent environment.

```shell
vagrant up
```

--------------------------------

### Initialize Beeminder User Client

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Sets up the Beeminder client in Ruby to interact with the API. Ensure you have the 'beeminder' gem installed.

```ruby
require 'beeminder'

bee = Beeminder::User.new "yourtoken"
bee.info
```

--------------------------------

### Example Datapoint JSON Response

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This is an example of the JSON structure returned when fetching datapoints for a goal. Each object represents a single datapoint with its associated attributes.

```json
[{"id":"1", "timestamp":1234567890, "daystamp":"20090213", "value":7, "comment":"", "updated_at":123, "requestid":"a"},
 {"id":"2", "timestamp":1234567891, "daystamp":"20090214", "value":8, "comment":"", "updated_at":123, "requestid":"b"}]
```

--------------------------------

### Example API Call with Auth Token

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Demonstrates how to include your authentication token in an API request to fetch data from your Beeminder account.

```APIDOC
## GET /api/v1/users/{username}/goals/{goalname}.json

### Description
Queries information about a specific goal for your Beeminder account.

### Method
GET

### Endpoint
https://www.beeminder.com/api/v1/users/{username}/goals/{goalname}.json

### Parameters
#### Query Parameters
- **auth_token** (string) - Required - Your personal authentication token.

### Request Example
```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/weight.json?auth_token=abc123
```

### Response
#### Success Response (200)
- **goal_data** (object) - Contains details about the specified goal.

### Response Example
```json
{
  "title": "Weight",
  "goal_type": "linear",
  "current_value": 150,
  "target_value": 140,
  "due_date": "2023-12-31"
}
```
```

--------------------------------

### Goal Object Response

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Example JSON response for a single goal, including its attributes and optionally, its datapoints.

```json
{
  "slug": "weight",               
  "title": "Weight Loss",         
  "goaldate": 1358524800,         
  "goalval": 166,                 
  "rate": null,                   
  "svg_url":   "http://static.beeminder.com/alice+weight.svg",
  "graph_url": "http://static.beeminder.com/alice+weight.png",
  "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",    
  "goal_type": "fatloser",            
  "losedate": 1358524800,        
  "queued": false,                
  "updated_at": 1337479214,       
  "datapoints": [{"timestamp": 1325523600,    
                    "value": 70.45,            
                    "comment": "blah blah",     
                    "id": "4f9dd9fd86f22478d3"},
                   {"timestamp": 1325610000,
                    "value": 70.85,
                    "comment": "blah blah",
                    "id": "5f9d79fd86f33468d4"}]}

}
```

--------------------------------

### List of Goals Response

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Example JSON response containing an array of goal objects for a user. Goals are sorted by urgency.

```json
[
  { "slug": "gmailzero",
      "title": "Inbox Zero",
      "goal_type": "inboxer",
      "svg_url": "http://static.beeminder.com/alice+gmailzero.svg",
      "graph_url": "http://static.beeminder.com/alice+gmailzero.png",
      "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
      "losedate": 1347519599,
      "goaldate": 0,
      "goalval": 25.0,
      "rate": -0.5,
      "updated_at": 1345774578,
      "queued": false },
  { "slug": "fitbit-me",
      "title": "Never stop moving",
      "goal_type": "hustler",
      "svg_url": "http://static.beeminder.com/alice+fitbit-me.svg",
      "graph_url": "http://static.beeminder.com/alice+fitbit-me.png",
      "thumb_url": "http://static.beeminder.com/alice+fitbit-thumb.png",
      "losedate": 1346482799,
      "goaldate": 1349582400,
      "goalval": null,
      "rate": 8.0,
      "updated_at": 1345771188,
      "queued": false }
]

```

--------------------------------

### Beeminder Authorization URL Example

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Construct the URL to send users to for authorizing your application. Ensure client_id, redirect_uri, and response_type are correctly set and URL-encoded if necessary.

```text
https://www.beeminder.com/apps/authorize?client_id=xyz456&redirect_uri=http://foo.com/auth_callback&response_type=token
```

--------------------------------

### Create a 'Weight Loss' Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

Construct this URL to set up a weight loss goal starting at 200 lbs with a 2 lb daily fluctuation. The 'flux' parameter is required for weight goals.

```url
https://www.beeminder.com/new?goaltype=weightloss&units=lbs&start_value=200&flux=2&goalname=getthinner
```

--------------------------------

### Access Token and Username Callback Example

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This is the format of the URL parameters appended when a user is redirected back after authorizing your app. Your server should parse these to retrieve the access_token and username.

```text
?access_token=abc123&username=alice
```

--------------------------------

### Charge Resource Response

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This is an example of the JSON response received after successfully creating a charge. It includes the charge ID, amount, note, and username.

```json
{ "id": "5016fa9adad11576ad00000f",
    "amount": 10,
    "note": "I'm not worthy; charge myself $10",
    "username": "alice" }
```

--------------------------------

### Get All Datapoints for a Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves a list of all datapoints associated with a specific user's goal. Ensure you have the correct authentication token.

```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints.json?auth_token=abc123
```

--------------------------------

### Get a Specific Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieve detailed information for a specific user goal. Include `datapoints=true` to fetch all associated data points.

```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/weight.json?auth_token=abc123&datapoints=true
```

--------------------------------

### Authenticated API Request

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Examples of how to include the access token in API requests, either as a query parameter or in the Authorization header.

```APIDOC
## Authenticating API Requests

### Description
Include your obtained `access_token` in API requests to authenticate on behalf of the user. You can use either a query parameter or the `Authorization` header.

### Method
GET

### Endpoint
/api/v1/users/me.json

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The user's access token.

### Request Example
```shell
curl https://www.beeminder.com/api/v1/users/me.json?access_token=abc123
```

### Headers
- **Authorization**: `Bearer <access_token>`

### Request Example
```shell
curl -H "Authorization: Bearer abc123" https://www.beeminder.com/api/v1/users/me.json
```

### Note
'me' can be used as a shortcut for the authorized user's username in any endpoint.
```

--------------------------------

### Get basic user information

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Fetches the username, timezone, updated timestamp, and a list of goal slugs for a given user. Use this for a quick overview of a user's profile.

```shell
curl https://www.beeminder.com/api/v1/users/alice.json?auth_token=abc123

{
  "username": "alice",
  "timezone": "America/Los_Angeles",
  "updated_at": 1343449880,                       
  "goals": ["gmailzero", "weight"]
}
```

--------------------------------

### Get all goals for a user

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves a list of all active goals for a specified user. The goals are returned sorted by urgency.

```APIDOC
## GET /users/{u}/goals.json

### Description
Get user *u*'s list of goals.

### Method
GET

### Endpoint
`/users/{u}/goals.json`

### Parameters
#### Query Parameters
- `emaciated` (boolean): If included the goal attributes called `road`, `roadall`, and `fullroad` will be stripped from the goal objects. Default: false.

### Returns
A list of [Goal](#goal) objects for the user. Goals are sorted in descending order of urgency, i.e., increasing order of time to derailment.
```

--------------------------------

### Webhook POST Data Example

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This JSON structure represents the data Beeminder will POST to your specified webhook URL when a goal is about to derail. It contains goal-specific information.

```json
{ "goal":
    { "id": "5016fa9adad11576ad00000f",
    "slug": "example", ... }
  }
```

--------------------------------

### Get archived goals for a user

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves a list of all archived goals for a specified user.

```APIDOC
## GET /users/{u}/goals/archived.json

### Description
Get user *u*'s archived goals.

### Method
GET

### Endpoint
`/users/{u}/goals/archived.json`

### Parameters
#### Query Parameters
- `emaciated` (boolean): If included the goal attributes called `road`, `roadall`, and `fullroad` will be stripped from the goal objects. Default: false.

### Returns
A list of [Goal](#goal) objects for the user.
```

--------------------------------

### Get All Goals for a User

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieve a list of all active goals for a given user. The `emaciated` parameter can be used to exclude road data.

```shell
curl https://www.beeminder.com/api/v1/users/alice/goals.json?auth_token=abc123
```

--------------------------------

### Get User Information

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves information and a list of goalnames for a specified user. You can also fetch data for the authenticated user by using `/users/me.json`.

```APIDOC
## GET /users/`u`.json

### Description
Retrieves information and a list of goalnames for the user with username `u`. 
Since appending an `access_token` to the request uniquely identifies a user, you can alternatively make the request to `/users/me.json` (without the username).

### Method
GET

### Endpoint
`/users/`*u*`.json`

### Parameters
#### Query Parameters
- **auth_token** (string) - Required - Your Beeminder authentication token.
- **associations** (boolean) - Optional - Fetch all information about a user, including all goals and datapoints. Defaults to false.
- **diff_since** (number) - Optional - Unix timestamp in seconds. Returns goals and datapoints updated since this timestamp. If not present, all goals and datapoints are returned. Defaults to null.
- **skinny** (boolean) - Optional - If true, returns a subset of goal attributes and only the most recent datapoint for each goal. Must be sent along with `diff_since`. Defaults to false.
- **emaciated** (boolean) - Optional - If true, strips `road`, `roadall`, and `fullroad` attributes from goal objects. Defaults to false.
- **datapoints_count** (number) - Optional - Specifies the number of most recently added datapoints to retrieve for each goal. Defaults to null (all datapoints).

### Request Example
```shell
curl https://www.beeminder.com/api/v1/users/alice.json?auth_token=abc123
```

### Response
#### Success Response (200)
- **username** (string) - The user's username.
- **timezone** (string) - The user's timezone.
- **updated_at** (number) - Unix timestamp of the last update to the user or their goals/datapoints.
- **goals** (array) - A list of goal slugs or goal hashes (objects).
- **deadbeat** (boolean) - True if the user's payment info is out of date or a payment failed.
- **urgency_load** (number) - A score indicating how edge-skatey the user is across all goals.
- **deleted_goals** (array) - An array of hashes, each with the id of a deleted goal. Only returned if `diff_since` is sent.

#### Response Example
```json
{
  "username": "alice",
  "timezone": "America/Los_Angeles",
  "updated_at": 1343449880,
  "goals": ["gmailzero", "weight"]
}
```
```

--------------------------------

### Get user information with recent goal and datapoint data

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves user details along with associated goals and their recent datapoints. This is useful for analyzing goal progress since a specific time.

```shell
curl https://www.beeminder.com/api/v1/users/alice.json?diff_since=1352561989&auth_token=abc123
```

--------------------------------

### Authenticate API Request with Personal Token

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Use this pattern to make API calls to your own Beeminder account. Append your auth_token as a GET or POST parameter to the API request.

```shell
  curl https://www.beeminder.com/api/v1/users/alice/goals/weight.json?auth_token=abc123
```

--------------------------------

### Ratchet Success and Error Responses

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Example JSON responses for the 'ratchet' endpoint. Success shows an updated goal object, while errors indicate issues like invalid 'newsafety' values or missing 'beemergency' flag.

```json
  // Example success:
  // updated goal object
  { "slug": "exercise",                       
    "goal_type": "hustler",                    
    "svg_url": "http://static.beeminder.com/alice+exercise.svg",
    "graph_url": "http://static.beeminder.com/alice+exercise.png",
    "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
    "goaldate": null,                 
    "goalval": 100,                         
    "rate": 1,
    "safebuf": 2,
    ...
    "losedate": 1358524800 }

  // Example error:
  {"errors": "newsafety cannot exceed 5"}
  {"errors": "Ratcheting to 0 days of buffer requires beemergency=True on the API call"}
  {"errors": "Goal cannot be ratcheted (may be archived, ended, or have no buffer)"}
```

--------------------------------

### Uncle Call Success and Error Responses

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Example JSON responses for calling the 'uncleme' endpoint. The success response shows an updated goal object, while the error response indicates why the action failed.

```json
  // Example success:
  // updated goal object
  { "slug": "blah",                       
    "goal_type": "hustler",                    
    "svg_url": "http://static.beeminder.com/alice+blah.svg",
    "graph_url": "http://static.beeminder.com/alice+blah.png",
    "thumb_url": "http://static.beeminder.com/alice+blah-thumb.png",
    "goaldate": null,                 
    "goalval": 166,                         
    "rate": 0.5,                           
    ...
    "losedate": 1358524800 }

  // Example error:
  {"errors": "Can't uncle a goal that's not in the red."}
```

--------------------------------

### Authenticate and Redirect User

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Use this cURL command to authenticate a user and redirect them to a specified URL. This is useful for third-party applications to guide users to specific parts of the Beeminder website without requiring them to log in again.

```shell
curl https://www.beeminder.com/api/v1/users/alice.json?auth_token=abc123&redirect_to_url=https%3A%2F%2Fwww.beeminder.com%2Fpledges
```

--------------------------------

### Get All Datapoints for a Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves a list of all datapoints associated with a specific user's goal. This includes historical data points with their timestamps, values, and other metadata.

```APIDOC
## GET /users/{u}/goals/{g}/datapoints.json

### Description
Get the list of datapoints for user *u*'s goal *g* &mdash; beeminder.com/*u*/*g*.

### Method
GET

### Endpoint
/users/{u}/goals/{g}/datapoints.json

### Parameters
#### Query Parameters
- **auth_token** (string) - Required - Authentication token for the user.

### Response
#### Success Response (200)
- **id** (string) - A unique ID, used to identify a datapoint when deleting or editing it.
- **timestamp** (number) - The unix time (in seconds) of the datapoint.
- **daystamp** (string) - The date of the datapoint (e.g., "20150831").
- **value** (number) - The value, e.g., how much you weighed on the day indicated by the timestamp.
- **comment** (string) - An optional comment about the datapoint.
- **updated_at** (number) - The unix time that this datapoint was entered or last updated.
- **requestid** (string) - If a datapoint was created via the API and this parameter was included, it will be echoed back.
- **origin** (string) - A short code related to where the datapoint came from.
- **creator** (string) - Similar to origin, but for users.
- **is_dummy** (boolean) - Not a logical datapoint.
- **is_initial** (boolean) - The initial datapoint added at goal creation time.
- **created_at** (time) - The timestamp at which the datapoint was created.

### Request Example
```shell
  curl https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints.json?auth_token=abc123
```

### Response Example
```json
  [{"id":"1", "timestamp":1234567890, "daystamp":"20090213", "value":7, "comment":"", "updated_at":123, "requestid":"a"},
   {"id":"2", "timestamp":1234567891, "daystamp":"20090214", "value":8, "comment":"", "updated_at":123, "requestid":"b"}]
```
```

--------------------------------

### Get information about a goal

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieves detailed information for a specific user's goal, identified by username and goal slug. Optionally includes datapoints and strips certain attributes.

```APIDOC
## GET /users/{u}/goals/{g}.json

### Description
Gets goal details for user *u*'s goal *g* &mdash; beeminder.com/*u*/*g*.

### Method
GET

### Endpoint
`/users/{u}/goals/{g}.json`

### Parameters
#### Query Parameters
- `datapoints` (boolean): Whether to send the goal's datapoints in the response. Default: `false`.
- `emaciated` (boolean): If included the goal attributes called `road`, `roadall`, and `fullroad` will be stripped from the goal object. Default: false.

### Returns
A [Goal](#goal) object, possibly without the datapoints attribute.
```

--------------------------------

### Get Personal Authentication Token

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Visit the provided URL to retrieve your personal authentication token. This token can then be appended to API requests as a GET or POST parameter for authentication.

```APIDOC
## GET /api/v1/auth_token.json

### Description
Retrieves your personal authentication token.

### Method
GET

### Endpoint
https://www.beeminder.com/api/v1/auth_token.json

### Parameters
None

### Response
#### Success Response (200)
- **auth_token** (string) - Your personal authentication token.

### Response Example
```json
{
  "auth_token": "your_personal_auth_token"
}
```
```

--------------------------------

### Create a 'Do More' Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

Use this URL to pre-fill a 'Do More' goal for 5 pushups per day. Ensure the user is logged in.

```url
https://www.beeminder.com/new?goaltype=domore&units=pushups&dailyrate=5&goalname=pushups
```

--------------------------------

### Deprecated: Dial Road Example Result

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

The result of a dial_road request shows the updated goal parameters.

```json
{
  "slug": "weight",                       
  "title": "Weight Loss",                 
  "goal_type": "fatloser",                    
  "svg_url": "http://static.beeminder.com/alice+weight.svg",
  "graph_url": "http://static.beeminder.com/alice+weight.png",
  "thumb_url": "http://static.beeminder.com/alice+weight-thumb.png",
  "goaldate": null,                 
  "goalval": 166,                         
  "rate": -0.5,                           
  "losedate": 1358524800 
}
```

--------------------------------

### Deploy Documentation

Source: https://github.com/beeminder/apidocs/blob/master/README.md

Deploys the latest changes to the Beeminder API documentation. This script should be run after committing and pushing changes to the master branch.

```shell
./deploy.sh
```

--------------------------------

### Troubleshooting

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Common issues include using incorrect URLs (e.g., `http` instead of `https`, or omitting `www`) and using the wrong HTTP request method for an endpoint. Always use the canonical Beeminder URL and pay attention to `POST` vs. `PUT` requests.

```APIDOC
## Troubleshooting

A common mistake is to use the wrong URL, e.g., using an `http` protocol instead of `https`, or leaving out the `www` subdomain. We redirect insecure and non `www` requests to the canonical Beeminder URL, but do not forward parameters for `POST` requests, so some things will break opaquely if you don't use exactly the above base URL. (And even worse, others will not.)

Also, please pay attention to the type of HTTP request an endpoint is expecting. For example, the `Goal#create` endpoint and `Goal#update` endpoint differ primarily in whether you are making a `POST` or a `PUT` request (respectively).
```

--------------------------------

### Create a 'Custom' Goal with Safety Buffer

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This URL creates a custom reading goal of 10 pages per day, with a 7-day initial safety buffer. The 'leeway' parameter specifies the buffer duration.

```url
https://www.beeminder.com/new?goaltype=custom&units=pages&dailyrate=10&leeway=7&goalname=reading
```

--------------------------------

### Create a Charge using cURL

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This snippet demonstrates how to create a charge for a Beeminder user using the `curl` command. Ensure you provide a valid `auth_token` and specify the `user_id`, `amount`, and an optional `note`.

```shell
curl -X POST 'https://www.beeminder.com/api/v1/charges.json' \
    -d auth_token=abc123 \
    -d user_id=alice \
    -d amount=10 \
    -d note=I%27m+not+worthy%3B+charge+myself+%2410
```

--------------------------------

### Ratchet to Beemergency

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Allows ratcheting a goal to 0 days of buffer, effectively setting it to beemergency. Requires 'beemergency=True' to be included in the API call.

```shell
  # Ratchet to beemergency (requires beemergency=True for safety)
  curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/exercise/ratchet.json \
    -d auth_token=abc123 \
    -d newsafety=0 \
    -d beemergency=True
```

--------------------------------

### Clone Repository

Source: https://github.com/beeminder/apidocs/blob/master/README.md

Clones the forked repository of the Beeminder API documentation to your local machine. Replace YOURUSERNAME with your GitHub username.

```shell
git clone https://github.com/YOURUSERNAME/apidocs.git
```

--------------------------------

### Create a single datapoint using cURL

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Use this command to create a single datapoint for a goal. Ensure you replace placeholders with your actual auth token, goal, and datapoint details. The timestamp can be a Unix epoch time or omitted to default to the current time.

```shell
curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints.json \
    -d auth_token=abc123 \
    -d timestamp=1325523600 \
    -d value=130.1 \
    -d comment=sweat+a+lot+today
```

--------------------------------

### Generate Goal Creation URL in Python

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This Python function helps construct a Beeminder goal creation URL with specified parameters. It supports additional optional parameters for customization.

```python
import urllib.parse

def create_goal_url(goaltype, units, dailyrate, goalname, **kwargs):
    params = {
        'goaltype': goaltype,
        'units': units,
        'dailyrate': dailyrate,
        'goalname': goalname,
        **kwargs
    }
    query_string = urllib.parse.urlencode(params)
    return f"https://www.beeminder.com/new?{query_string}"

# Example usage
url = create_goal_url(
    goaltype='domore',
    units='pages',
    dailyrate=10,
    goalname='reading',
    leeway=7,
    pledge_cap=30
)
print(url)
```

--------------------------------

### Get Archived Goals for a User

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Retrieve a list of a user's archived goals. Similar to active goals, the `emaciated` parameter can be used to omit road data.

```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/archived.json?auth_token=abc123
```

--------------------------------

### Create a Goal

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Use this cURL command to create a new goal for a user. Ensure all required parameters like slug, title, and goal type are provided.

```shell
curl -X POST https://www.beeminder.com/api/v1/users/alice/goals.json \
    -d auth_token=abc123 \
    -d slug=exercise \
    -d title=Work+Out+More \
    -d goal_type=hustler \
    -d goaldate=1400000000 \
    -d gunits=workouts \
    -d rate=5 \
    -d goalval=null
```

--------------------------------

### User data with detailed goal and datapoint information

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Returns comprehensive user data, including detailed goal information and a list of datapoints for each goal. This is returned when `diff_since` or `associations=true` is used.

```json
{
  "username": "alice",
  "timezone": "America/Los_Angeles",
  "updated_at": 1343449880,                       
  "goals": [ {"slug": "weight", ...,
               "datapoints": [{"timestamp": 1325523600,    
                    "value": 70.45,            
                    "comment": "blah blah",     
                    "id": "4f9dd9fd86f22478d3"},
                   {"timestamp": 1325610000,
                    "value": 70.85,
                    "comment": "blah blah",
                    "id": "5f9d79fd86f33468d4"}],
               "title": "Weight Loss", ...},
               { another goal }, ... ],
    "deleted_goals": [{ "id": "519279fd86f33468ne"}, ... ] 
}
```

--------------------------------

### Create Bookmarklet for Goal Creation

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

Use this JavaScript bookmarklet to quickly create a new Beeminder goal for the current web page. It automatically extracts the page title and opens the Beeminder goal creation page with pre-filled parameters.

```javascript
javascript:(function(){
  var title = document.title.substring(0,20).toLowerCase().replace(/[^a-z0-9]/g,'');
  var url = 'https://www.beeminder.com/new?goaltype=domore&units=items&dailyrate=1&goalname=' + title;
  window.open(url);
})();
```

--------------------------------

### Create Goal from Browser Extension

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This JavaScript function is designed for browser extensions to create a Beeminder goal. It generates the URL with provided parameters and opens it in a new tab.

```javascript
// Create a goal from a browser extension
function createBeeminderGoal(params) {
  const queryString = new URLSearchParams(params).toString();
  const url = `https://www.beeminder.com/new?${queryString}`;
  chrome.tabs.create({ url: url });
}

// Usage
createBeeminderGoal({
  goaltype: 'domore',
  units: 'articles',
  dailyrate: 2,
  goalname: 'reading',
  leeway: 3
});
```

--------------------------------

### Access Token and Username Callback

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

After user authorization, Beeminder redirects to the specified redirect_uri with access_token and username appended as query parameters.

```APIDOC
## Callback after Authorization

### Description
Upon successful user authorization, Beeminder redirects the user to your specified `redirect_uri` with the `access_token` and `username` as query parameters.

### Parameters
#### Query Parameters
- **access_token** (string) - The token granting your application access to the user's data.
- **username** (string) - The username of the authorized user.
```

--------------------------------

### Create a goal for a user

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Creates a new goal for a specified user. Requires parameters like slug, title, goal type, and units. Exactly two of goaldate, goalval, and rate are required.

```APIDOC
## POST /users/{u}/goals.json

### Description
Create a new goal for user *u*.

### Method
POST

### Endpoint
/users/{u}/goals.json

### Parameters
#### Path Parameters
* `u` (string) - The user's identifier.

#### Request Body
* `slug` (string) - Required - The unique identifier for the goal.
* `title` (string) - Required - The display name for the goal.
* `goal_type` (string) - Required - The type of goal (e.g., 'hustler').
* `gunits` (string) - Required - The units for the goal.
* `goaldate` (number or null) - Required (in combination with goalval and rate) - The target date for the goal.
* `goalval` (number or null) - Required (in combination with goaldate and rate) - The target value for the goal.
* `rate` (number or null) - Required (in combination with goaldate and goalval) - The rate at which the goal should progress.
* `initval` (number) - Optional - Initial value for today's date. Defaults to 0.
* `secret` (boolean) - Optional - Whether the goal is private.
* `datapublic` (boolean) - Optional - Whether data for this goal is public.
* `datasource` (string) - Optional - Specifies the data source (e.g., "api", "ifttt"). Defaults to "manual".
* `dryrun` (boolean) - Optional - If true, tests the endpoint without creating a goal. Defaults to false.
* `tags` (array) - Optional - A list of tags to add to the new goal.

### Request Example
```shell
curl -X POST https://www.beeminder.com/api/v1/users/alice/goals.json \
  -d auth_token=abc123 \
  -d slug=exercise \
  -d title=Work+Out+More \
  -d goal_type=hustler \
  -d goaldate=1400000000 \
  -d gunits=workouts \
  -d rate=5 \
  -d goalval=null
```

### Response
#### Success Response (200)
Returns the newly created Goal object.

### Response Example
```json
{
  "slug": "exercise",
  "title": "Work Out More",
  "goal_type": "hustler",
  "svg_url": "http://static.beeminder.com/alice+exercise.svg",
  "graph_url": "http://static.beeminder.com/alice+exercise.png",
  "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
  "losedate": 1447519599,
  "goaldate": 1400000000,
  "goalval": null,
  "rate": 5,
  "updated_at": 1345774578,
  "queued": false
}
```
```

--------------------------------

### Deprecated: Update Bright Red Line

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Deprecated endpoint to change the slope of the bright red line (yellow brick road) for a goal, starting after the Akrasia Horizon. It is recommended to use the `roadall` parameter on the goal update endpoint instead.

```APIDOC
## POST /users/{u}/goals/{g}/dial_road.json

### Description
[Deprecated] Changes the slope of the bright red line (yellow brick road) for a goal.

### Method
POST

### Endpoint
`/users/{u}/goals/{g}/dial_road.json`

### Parameters
* `rate` (number or null) - The new rate for the bright red line.
* `goaldate` (number or null) - The new target date for the goal.
* `goalval` (number or null) - The new target value for the goal.

Exactly two of `goaldate`, `goalval`, and `rate` must be specified.

### Returns
The updated [Goal](#goal) object.
```

--------------------------------

### Autofetch Callback

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Optional POST request to a specified callback URL when Beeminder needs new data from your application.

```APIDOC
## POST /autofetch

### Description
Beeminder may send a POST request to your registered autofetch callback URL when it requires updated data from your application. This is triggered by manual refresh actions or specific system events.

### Method
POST

### Parameters
#### Request Body
- **username** (string) - The username associated with the data request.
- **slug** (string) - The goal slug associated with the data request.
```

--------------------------------

### Short Circuit Goal Pledge

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This endpoint increases a goal's pledge level and charges the user the amount of the current pledge immediately.

```shell
POST /users/*u*/goals/*g*/shortcircuit.json
```

--------------------------------

### Create multiple datapoints

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Creates multiple new datapoints for a specified goal. It accepts an array of datapoint objects.

```APIDOC
## POST /users/{u}/goals/{g}/datapoints/create_all.json

Create multiple new datapoints for beeminder.com/*u*/*g*.

### Parameters

* `datapoints` (array of Datapoints) - Required. Each Datapoint object must include at minimum a `value`. Other parameters are the same as for the single-create method.

### Returns

A list of successfully created [Datapoints](#datapoint). Or, in the case of any errors, an object with two lists: `successes`, and `errors`.
```

--------------------------------

### New Goal Response

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This JSON object represents the successful creation of a new goal, including its properties and URLs.

```json
{ "slug": "exercise",
    "title": "Work Out More",
    "goal_type": "hustler",
    "svg_url": "http://static.beeminder.com/alice+exercise.svg",
    "graph_url": "http://static.beeminder.com/alice+exercise.png",
    "thumb_url": "http://static.beeminder.com/alice+exercise-thumb.png",
    "losedate": 1447519599,
    "goaldate": 1400000000,
    "goalval": null,
    "rate": 5,
    "updated_at": 1345774578,
    "queued": false }
```

--------------------------------

### Call Uncle (Instant Derail)

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Use this endpoint to immediately derail a goal that is in danger of derailing. This will charge the pledge amount and stop all alerts. It will fail if the goal has more than 0 days of buffer.

```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/blah/uncleme.json?auth_token=abc123
```

--------------------------------

### URL for Reserved Goal Name Error

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This URL demonstrates the parameters that result in a 'Reserved Goal Name' error. The goal name 'new' is a reserved keyword and cannot be used.

```url
https://www.beeminder.com/new?goaltype=domore&units=pages&dailyrate=5&goalname=new
```

--------------------------------

### Call "Uncle" (i.e. instant derail)

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Call "Uncle" on a goal that is imminently going to derail. This endpoint insta-derails the goal, stopping all alerts, charging the pledge amount, and inserting your post-derail respite into the graph. USE AT YOUR OWN RISK.

```APIDOC
## POST /users/{u}/goals/{g}/uncleme.json

### Description
Call "Uncle" on a goal that is imminently going to derail (aka is in a beemergency, or "is red"). This endpoint insta-derails the goal, stopping all alerts, charging the pledge amount, and inserting your post-derail respite into the graph. USE AT YOUR OWN RISK. This endpoint will fail if the goal has more than 0 days of buffer. This endpoint will charge you -- and all Groupies of the goal -- immediately for the derail. There are no takebacks, no undos, and no refunds.

### Method
POST

### Endpoint
`/users/{u}/goals/{g}/uncleme.json`

### Parameters

None

### Request Example
```shell
curl https://www.beeminder.com/api/v1/users/alice/goals/blah/uncleme.json?auth_token=abc123
```

### Response
#### Success Response
- The updated [Goal](#goal) object.

#### Response Example
```json
{
  "slug": "blah",
  "goal_type": "hustler",
  "svg_url": "http://static.beeminder.com/alice+blah.svg",
  "graph_url": "http://static.beeminder.com/alice+blah.png",
  "thumb_url": "http://static.beeminder.com/alice+blah-thumb.png",
  "goaldate": null,
  "goalval": 166,
  "rate": 0.5,
  ...
  "losedate": 1358524800
}
```

#### Error Response
- An error if the goal is not red.

#### Error Response Example
```json
{"errors": "Can't uncle a goal that's not in the red."}
```
```

--------------------------------

### Create a datapoint

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Adds a new datapoint to a user's goal. This endpoint supports upsert functionality using a `requestid` for idempotency.

```APIDOC
## POST /users/{u}/goals/{g}/datapoints.json

Adds a new datapoint to user *u*'s goal *g* &mdash; beeminder.com/*u*/*g*.

### Parameters

* `value` (number) - Required
* `timestamp` (number) - Optional. Defaults to "now".
* `daystamp` (string) - Optional. Can be used instead of `timestamp`. If both are included, `timestamp` takes precedence.
* `comment` (string) - Optional.
* `requestid` (string) - Optional. A unique identifier for the datapoint, used for idempotency and upsert operations.

### Returns

The updated [Datapoint](#datapoint) object.
```

--------------------------------

### Response for creating multiple datapoints

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This JSON array shows the result of creating multiple datapoints. Each object in the array represents a successfully created datapoint, including its ID, timestamp, value, and `requestid`.

```json
[ { "id": "5016fa9adad11576ad00000f",
      "timestamp": 1343577600,
      "daystamp": "20120729",
      "value": 220.6,
      "comment": "blah blah",
      "updated_at": 1343577600,
      "requestid":"abcd182475923"},
    { "id": "5016fa9bdad11576ad000010",
      "timestamp": 1343491200,
      "daystamp": "20120728",
      "value": 220.7,
      "comment": "",
      "updated_at": 1343491200,
      "requestid":"abcd182475923" } ]
```

--------------------------------

### Create multiple datapoints using cURL

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This cURL command demonstrates how to create multiple datapoints in a single request. The datapoints are provided as a JSON array in the `datapoints` parameter. Each object in the array can include `timestamp`, `value`, `comment`, and `requestid`.

```shell
curl -X POST https://www.beeminder.com/api/v1/users/alice/goals/weight/datapoints/create_all.json \
    -d auth_token=abc123 \
    -d datapoints=[{"timestamp":1343577600,"value":220.6,"comment":"blah+blah", "requestid":"abcd182475929"}, {"timestamp":1343491200,"value":220.7, "requestid":"abcd182475930"}]
```

--------------------------------

### URL for Duplicate Goal Name Error

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This URL shows the parameters that trigger a 'Duplicate Goal Name' error. The goal name 'existinggoal' already exists for the user.

```url
https://www.beeminder.com/new?goaltype=domore&units=pages&dailyrate=5&goalname=existinggoal
```

--------------------------------

### API Request with Access Token

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Include the user's access token in API requests either as a query parameter or in the Authorization header. The 'me' keyword can be used as a shortcut for the authorized user's username.

```shell
curl https://www.beeminder.com/api/v1/users/me.json?access_token=abc123
```

```shell
curl -H "Authorization: Bearer abc123" https://www.beeminder.com/api/v1/users/me.json
```

--------------------------------

### Response for creating a single datapoint

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

This JSON object represents the successful creation of a single datapoint. It includes the assigned ID, timestamp, value, and any associated comment.

```json
{ "timestamp": 1325523600,
    "daystamp": "20120102",
    "value": 130.1,         
    "comment": "sweat a lot today",   
    "id": "4f9dd9fd86f22478d3000008",
    "requestid":"abcd182475925" }
```

--------------------------------

### URL for Flux on Non-Weight Goal Error

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This URL illustrates the 'Flux on Non-Weight Goal' error. The 'flux' parameter is incorrectly used with a 'do more' goal type.

```url
https://www.beeminder.com/new?goaltype=domore&units=pages&dailyrate=5&goalname=test&flux=2
```

--------------------------------

### Authenticate and redirect the user

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Attempts to authenticate the user and redirects to the given URL if successful. This allows third-party apps to send users to specific website sections without a login screen.

```APIDOC
## GET /users/{u}.json

### Description
Attempts to authenticate the user and if successful redirects to the given URL. Allows third-party apps to send the user to a specific part of the website without getting intercepted by a login screen, for doing things not available through the API.

### Method
GET

### Endpoint
`/users/`*u*`.json`

### Parameters
#### Query Parameters
- **redirect_to_url** (string): Url to redirect the user to.
- **auth_token** (string): Authentication token for the user.
```

--------------------------------

### URL for Invalid Goal Name Error

Source: https://github.com/beeminder/apidocs/blob/master/source/includes/_url_goal_creation.md

This URL demonstrates the parameters that trigger an 'Invalid Goal Name' error. The goal name contains spaces, which are not permitted.

```url
https://www.beeminder.com/new?goaltype=domore&units=pages&dailyrate=5&goalname=my goal
```

--------------------------------

### Create Charge

Source: https://github.com/beeminder/apidocs/blob/master/source/index.html.md

Creates a charge for a Beeminder user. The user is identified by the provided auth token or access token.

```APIDOC
## POST /charges

### Description
Create a charge of a given amount and optionally add a note.

### Method
POST

### Endpoint
`/charges`

### Parameters
#### Query Parameters
- **user_id** (string) - Required - Username of the user who is getting charged.
- **amount** (number) - Required - The amount to charge the user, in US dollars. Minimum value is 1.00
- **note** (string) - Optional - An explanation of why the charge was made.
- **dryrun** (string) - Optional - If passed, the Charge is not actually created, but the JSON for it is returned as if it were. Default: false.

### Request Example
```shell
  curl -X POST 'https://www.beeminder.com/api/v1/charges.json' \
    -d auth_token=abc123 \
    -d user_id=alice \
    -d amount=10 \
    -d note=I%27m+not+worthy%3B+charge+myself+%2410 \
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created charge.
- **amount** (number) - The amount charged.
- **note** (string) - The note associated with the charge.
- **username** (string) - The username of the charged user.

#### Response Example
```json
  { "id": "5016fa9adad11576ad00000f",
    "amount": 10,
    "note": "I'm not worthy; charge myself $10",
    "username": "alice" }
```
```