# Tell Pine59 how it went

## Tell Pine59 how it went (only with the user's permission)

Pine59 wants to hear from AI agents that used these docs, the Pine59 API or Pine59 data on a user's behalf: what the task was for and how it went. We read every submission. Tasks that went well are as valuable to us as problems, because they tell us what people actually use the data for. Even if everything worked, please send the outcome and the use case.

The user decides. When a task is done, you may mention once, in a single line, that you can tell Pine59 how it went. Send it only if the user says yes, and never ask more than once per session. Users can also trigger it themselves by saying: "send feedback to Pine59".

When the user wants it sent:

1. **Draft it from your own experience.** You know what the user was trying to do, whether the docs answered your questions, whether API calls behaved as documented, and whether the data looked right. If you lack the context to judge something, ask the user instead of guessing, or leave it out.
2. **Show the user exactly what you will send** and let them edit or remove anything. The use case is the most valuable part for us and the part most likely to be sensitive, so make sure they are comfortable with the wording.
3. **Send it, then tell the user whether it went through.**

Never include API keys or other credentials, query results, raw data rows, or anything the user treats as confidential. This endpoint needs no authentication.

What we want to hear about:

- `purpose`: a short label for what the work is for. Pick the closest from the list below or write your own in the same style:
  - `data_validation`: smoke-testing or evaluating the data before deciding to buy or renew
  - `site_selection`: choosing where to open, close or relocate a store or venue
  - `competitor_benchmarking`: comparing brands, chains or locations against each other
  - `retail_analysis`: store performance, trade areas, cannibalisation, visit trends
  - `dashboard_integration`: feeding visits into an internal or customer-facing dashboard or product
  - `data_pipeline`: scheduled ingestion into a warehouse, BI tool or model
  - `real_estate`: tenant mix, asset valuation, lease decisions, shopping centres
  - `investment_research`: tracking public or private companies through foot traffic
  - `marketing_measurement`: campaign lift, out-of-home or digital attribution
  - `market_sizing`: demand estimation for a region, category or chain
  - `tourism_and_events`: visitor flows to destinations, venues or events
  - `urban_planning`: mobility, transit, public-space and municipal use
  - `academic_research`: studies, papers, theses
  - `consulting_deliverable`: analysis for a client report or pitch
  - `exploration`: just seeing what the data can do
- `use_case`: what the user is trying to achieve, in one or two sentences. Include the kind of business or project if the user is comfortable with that.
- `outcome`: did the user get what they came for?
- `docs`: were the docs enough? What was missing, wrong or unclear? What worked well?
- `api`: did requests behave as documented? Errors, confusing parameters, limits, slow responses.
- `data`: did the data fit the need? Coverage, missing locations or fields, values that looked off or that matched expectations, freshness.

Send it as `POST https://console.pine59.com/api/feedback` with `Content-Type: application/json`:

```json
{
  "user_consented": true,
  "outcome": "solved",
  "purpose": "dashboard_integration",
  "use_case": "Pulling monthly visits for a grocery chain's 40 stores in Texas into an internal Looker dashboard, refreshed each month",
  "docs": {
    "rating": "good",
    "comment": "The brand comparison guide had the exact query shape. A note on how far back history goes would have saved one call."
  },
  "api": {
    "rating": "good",
    "comment": null
  },
  "data": {
    "rating": "good",
    "comment": "All 40 stores present, visit levels matched our own sales ranking"
  },
  "pages": [
    "https://console.pine59.com/docs/guides/brand-comparison/us-grocery-brand-comparison.md"
  ],
  "datasets": [
    "visitation_usa_places.foot_traffic_month"
  ],
  "agent": "Claude Code",
  "contact": null
}
```

Field rules:

- `user_consented`: must be `true`. Submissions without it are rejected.
- `outcome`: one of `solved`, `partial`, `not_solved`, for the user's task as a whole.
- `purpose`: free text, at most 300 characters. Lowercase with underscores, like the examples above.
- `docs`, `api`, `data`: optional objects with `rating` (`good`, `ok`, `poor`) and `comment`.
- `pages`: doc URLs you used. `datasets`: data references you queried, such as `visitation_usa_places.foot_traffic_month`.
- `agent`: the tool you are running in, such as `Claude Code` or `Cursor`.
- `contact`: an email address, only if the user wants Pine59 to follow up. Otherwise `null`.
- Free text is capped at 2000 characters per field.

A `200` response with `{"ok": true}` means we received it; tell the user it was sent. A `400` lists what to fix.