مستندات API

هر چیزی که یک برنامه می‌تواند از «رصد» بپرسد: نشانی، دامنهٔ دسترسی، هزینه و شکل پاسخ.

این صفحه از همان فهرستی ساخته می‌شود که مسیرهای API از رویش ثبت می‌شوند، پس نمی‌تواند از چیزی بگوید که وجود ندارد: ۱۷ نقطهٔ پایانی در ۹ دامنهٔ دسترسی. نام فیلدها و کد خطاها انگلیسی‌اند و ترجمه نمی‌شوند؛ یک واسط ماشینی نیمه‌ترجمه‌شده بدتر از یک واسط صادقانهٔ تک‌زبانه است.

شروع

نشانی پایه: https://sahmino.com/api/v1
سربرگ احراز هویت: Authorization: Bearer <token>

A token minted for the MCP server is not an API token and will be refused.

یک درخواست نمونه

curl -H "Authorization: Bearer $SAHMINO_TOKEN" \
  https://sahmino.com/api/v1/instruments

ساختن کلید سند «OpenAPI»1.0.0

۲۴۰: درخواست در دقیقه
۱۰۰: ردیف در هر صفحه

دامنه‌های دسترسی

دامنهٔ دسترسی هنگام ساختن کلید تعیین می‌شود و پس از آن تغییر نمی‌کند. هر نقطهٔ پایانی دقیقاً یکی را می‌خواهد و مقایسه عیناً انجام می‌شود، پس کلید MCP اینجا هیچ دری را باز نمی‌کند.

دامنه	چه چیزی را می‌خواند
`api:instruments`	Read the instrument catalog, board rows and one instrument’s profile.
`api:prices`	Read price history and derived series for one instrument.
`api:indicators`	Read computed technical indicators for one instrument.
`api:screener`	Run a saved screen or an ad-hoc condition set over the universe.
`api:filings`	Read codal filings and the financial statements parsed from them.
`api:valuations`	Read saved valuation runs and their inputs.
`api:macro`	Read macroeconomic series.
`api:ownership`	Read the shareholder register and board composition graph.
`api:alerts`	Read alert rules and their delivery history.

شکل پاسخ

A single record answers {"data": {…}}.
A list answers {"data": [...], "meta": {"page", "perPage", "total", "lastPage"}}. perPage is fixed and is not caller-settable.
Every refusal answers {"error": {"code", "message", "detail?"}}. Branch on code; message is prose and may be reworded in any release.

خطاها

روی «code» شرط بگذارید، نه روی «message»: متن پیام ممکن است در هر نسخه بازنویسی شود، ولی کد همان می‌ماند.

کد	وضعیت HTTP	یعنی چه، و چه باید کرد
`unauthenticated`	401	No token, an expired one, or one that has been revoked. Mint a new token.
`scope_required`	403	The token is valid but was not granted the scope this endpoint declares. Mint one that carries it — a token’s scopes are fixed at mint.
`plan_required`	403	The account’s tier does not include API access. Nothing about the token can fix this.
`rate_limited`	429	The per-minute ceiling or the day’s request budget. Read Retry-After, and detail.retryAfter on the budget refusal.
`not_found`	404	The request was understood and names nothing we hold. An instrument is matched exactly, by id, symbol or slug.
`invalid_request`	422	A bad parameter, a missing one, or the wrong shape. detail.fields names each one.
`server_error`	500	Us. The message is deliberately generic; report it with the time of the call.

instruments

Read the instrument catalog, board rows and one instrument’s profile.

GET/api/v1/instrumentsیک صفحههزینه ۱api:instruments

The instrument catalog, paged.

Identity, venue and the last price we hold. Both language names travel, always.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`filter[market]`	string	One market type — gold, currency, tse and their like.
`filter[board]`	string	The listing venue, exactly.bourse · fara · fara_base
`filter[q]`	string	A search term over symbol and name, in either language.
`sort`	string	A sort key; prefix with «-» for descending.
`page`	integer	Which page, from one.

GET/api/v1/instruments/{instrument}یک رکوردهزینه ۲api:instruments

One instrument, with its exchange profile.

The catalog row plus the nightly profile reading: free float, market capitalisation, the sector it is filed under.

GET/api/v1/boardیک صفحههزینه ۱api:instruments

The day’s board — one page of it.

Last, close, change, volume, value and the retail share of each side. Yesterday’s close is on the instrument’s own price endpoint, not on every row of the board.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`group`	string	Which half of the board.all · equity · fund · fixed_income
`exchange`	string	The listing venue.bourse · fara · fara_base
`industry`	string	One industry, as the exchange spells it.
`search`	string	A term over symbol and name.
`sort`	string	What the whole match is ordered by before the page is cut.value · volume · change · last
`direction`	string	Ascending or descending.asc · desc
`page`	integer	Which page, from one.

prices

Read price history and derived series for one instrument.

GET/api/v1/instruments/{instrument}/pricesیک رکوردهزینه ۲api:prices

Daily history and the window statistics struck from it.

Points are oldest first; a halted session is a row like any other and says so. `unit` is load-bearing — rial and toman differ by a factor of ten.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`days`	integer	Rows of daily history, 20 to 365. Default 120.

indicators

Read computed technical indicators for one instrument.

GET/api/v1/instruments/{instrument}/indicatorsیک رکوردهزینه ۵api:indicators

The stored technical readings for one instrument.

Read back, never recomputed: `seriesHash` says which sessions they were struck from. An indicator with no reading is absent rather than null.

screener

Run a saved screen or an ad-hoc condition set over the universe.

GET/api/v1/screener/fieldsیک رکوردهزینه ۱api:screener

Every screenable field, with its group, format and label.

The catalog a client needs before it can write a condition. Generated from the field registry the screener itself draws.

GET/api/v1/screensیک رکوردهزینه ۱api:screener

The caller’s own saved screens.

Whole rather than paged — the shelf has a ceiling the account cannot write past. `meta.kept` against `meta.limit` says whether saving another would be refused.

POST/api/v1/screener/runیک رکوردهزینه ۲۵api:screener

Run a saved screen, or a set of conditions posted with the request.

A نماد with no reading on a field never passes a condition on it: an absent figure is not a zero. `matched` is how many passed; `shown` is how many travelled; `rowCap` is how many this plan allows in one call, or null for no cap.

بدنهٔ درخواست

پارامتر	نوع	توضیح
`screenId`	integer	A saved screen of the caller’s. When present, `screen` and `scope` are ignored.
`screen`	object	A condition set: `match` of «all» or «any», and up to 24 conditions of field, operator and value.
`scope`	object	Narrow the universe first: `group`, `exchange`, `industry`.
`fields`	array	Extra readings each row should carry, beyond the ones it was screened on.
`sortBy`	string	A field key the whole match is ordered by.
`sortDescending`	boolean	Largest first. Default true.

filings

Read codal filings and the financial statements parsed from them.

GET/api/v1/filingsیک صفحههزینه ۱api:filings

codal letters as filed, newest first.

`periodMonths` is the span the letter reports; comparing a three-month figure with a twelve-month one is the commonest way to publish a wrong number.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`symbol`	string	One نماد, by symbol or slug. An unknown one narrows to nothing.
`since`	string	Only letters published on or after this date.
`parsedOnly`	boolean	Only letters whose statements we have parsed.
`page`	integer	Which page, from one.

GET/api/v1/instruments/{instrument}/statementsیک رکوردهزینه ۲api:filings

The financial statements parsed out of one instrument’s filings.

How many periods travel is the tier’s `statement_periods` cell, and `quota` reports it beside the rows: `total` is how many the company filed, `shown` is how many the plan allows.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`letter`	integer	One letter id, to read the grid as that letter filed it.

valuations

Read saved valuation runs and their inputs.

GET/api/v1/valuationsیک رکوردهزینه ۱api:valuations

The caller’s saved valuation runs.

`gapAtSave` is the argument the reader was making; `gapNow` is what the market has done to it since.

GET/api/v1/instruments/{instrument}/valuationsیک رکوردهزینه ۲api:valuations

The caller’s saved runs for one instrument.

macro

Read macroeconomic series.

GET/api/v1/macroیک رکوردهزینه ۱api:macro

Every macro series we declare, with its freshness.

`freshAt` is the last write of the ingest behind the series and `stale` is that clock against the series’ own cadence — a monthly series with no observation this week is not late.

GET/api/v1/macro/seriesیک رکوردهزینه ۱api:macro

The observations of up to 5 series.

Points are oldest first and a day with no observation is absent, never zero. An unknown key is a 404 rather than an empty series.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`keys[]`الزامی	array	Series keys, as the catalog spells them.
`days`	integer	How far back, up to 3650.

ownership

Read the shareholder register and board composition graph.

GET/api/v1/instruments/{instrument}/ownershipیک رکوردهزینه ۵api:ownership

The shareholder register, the board and everything derived from them.

An individual’s کد ملی is never present: the query nulls it before the DTO is built.

alerts

Read alert rules and their delivery history.

GET/api/v1/alertsیک صفحههزینه ۱api:alerts

The caller’s alert rules, newest first.

Read only. A rule is written through the terminal, where the plan cap and the re-arm rule live. Paged because `alert_rules` is uncapped on the one tier this API answers.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`page`	integer	Which page, from one.

GET/api/v1/alerts/deliveriesیک صفحههزینه ۱api:alerts

What has already been sent, newest first.

The feed an integration wants: an alert that fired, so it can reach a system rather than only a person.

پارامترهای پرس‌وجو

پارامتر	نوع	توضیح
`page`	integer	Which page, from one.