First submission
Read the forecast requirements, prepare a JSON payload and submit it with a producer API key.
Prerequisites
Create a producer API key and store it in TELESCOPE_API_KEY. Your account must be enabled as a forecast provider. Contact support if onboarding is incomplete.
1. Read the requirements
curl --fail-with-body 'https://telescope.energy/api/v2/producer/definitions' \
-H "Authorization: Bearer $TELESCOPE_API_KEY"
Choose a returned key. Its definition tells you what to forecast: the time zone, resolution, required series, outputs and units. Its horizon and submissionRules tell you when and how much to submit.
For this example, use a definition with PT4H resolution, Europe/Berlin time zone, positive and negative series, and p10, p50 and p90 outputs. If your definition differs, build its required grid instead.
2. Prepare a complete JSON payload
Save your forecast as submission.json. The downloadable example contains all six intervals of one local delivery day. The dates and values are illustrative: choose a currently allowed delivery day whose deadline has not passed, use your own predictions, and set generatedAt to their actual generation time.
Each interval supplies all required series and outputs. This single-interval excerpt cannot be submitted on its own:
{
"validTime": "2026-10-07T22:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
}
Download the complete illustrative payload and replace its dates and predictions before sending it. To prepare predictions in CSV, use the optional offline Python helper.
{
"definition": "afrr-capacity-price-de",
"generatedAt": "2026-10-07T06:00:00Z",
"deliveryWindows": [
{
"deliveryDay": "2026-10-08",
"values": [
{
"validTime": "2026-10-07T22:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
},
{
"validTime": "2026-10-08T02:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
},
{
"validTime": "2026-10-08T06:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
},
{
"validTime": "2026-10-08T10:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
},
{
"validTime": "2026-10-08T14:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
},
{
"validTime": "2026-10-08T18:00:00Z",
"series": {
"positive": { "p10": 0.05, "p50": 0.09, "p90": 0.15 },
"negative": { "p10": 0.1, "p50": 0.2, "p90": 0.35 }
}
}
]
}
]
}
deliveryDay is a date in the definition’s time zone; each validTime is an interval start with an explicit UTC offset. Here, local midnight is 22:00 UTC on the previous date. Each timestamp includes every required series and output.
For a definition with no series or one series, you can also submit outputs directly at each timestamp, such as "outputs": { "p10": 0.05, "p50": 0.09, "p90": 0.15 }. Use exactly one of outputs or series per timestamp. Multiple configured series require the series form above.
Gate-closure submissions need complete days. Rolling submissions need at least 48 continuous hours and can include partial boundary days. Follow Submission scheduling to construct the correct range.
3. Send the forecast
Create a unique idempotency key for this submission and persist it alongside the payload. Reuse the same key and unchanged payload if a request times out.
export TELESCOPE_IDEMPOTENCY_KEY="$(uuidgen)"
# Save this key with submission.json before sending the request.
curl --fail-with-body 'https://telescope.energy/api/v2/producer/submissions' \
-H "Authorization: Bearer $TELESCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $TELESCOPE_IDEMPOTENCY_KEY" \
--data-binary @submission.json
import json
import os
from urllib.request import Request, urlopen
from pathlib import Path
request = Request(
"https://telescope.energy/api/v2/producer/submissions",
data=Path("submission.json").read_bytes(),
headers={
"Authorization": "Bearer " + os.environ["TELESCOPE_API_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": os.environ["TELESCOPE_IDEMPOTENCY_KEY"],
},
)
with urlopen(request, timeout=30) as response:
print(json.dumps(json.load(response), indent=2))
import { readFile } from "node:fs/promises"
const response = await fetch("https://telescope.energy/api/v2/producer/submissions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TELESCOPE_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": process.env.TELESCOPE_IDEMPOTENCY_KEY!,
},
body: await readFile("submission.json", "utf8"),
})
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())
4. Verify acceptance
A new submission returns 201 Created. This response excerpt shows the fields to keep:
{
"replayed": false,
"runId": "m57abc123",
"status": "accepted"
}
Save runId with your payload and idempotency key. The full response also reports accepted delivery windows and coverage. An identical retry returns 200 OK, the same runId and replayed: true.
Acceptance confirms that Telescope received the forecast; customer publication is a separate step. To inspect the accepted values, use the submission detail endpoint.
If the request fails
422 SUBMISSION_REJECTED means no forecast values were stored. Read details.issues, correct the payload and use a new key. For a timeout, retry the original body and key. See Validation & retries.
Optional Python helper
If you prefer preparing predictions in CSV, build_submission.py can generate a delivery grid and convert filled values into JSON. Run python3 build_submission.py --help for its options. It runs offline and is optional; any client that sends the documented JSON can submit forecasts.
Next steps
- Automate submission scheduling.
- Check time zones and units.
- Look up fields and limits in the Producer API.