مستندات 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

ساختن کلید سند OpenAPI1.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, previous close, change, volume, value and the retail share of each side.

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

پارامتر	نوع	توضیح
`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.

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; `data` is how many the plan let travel.

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

پارامتر	نوع	توضیح
`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.

Read only. A rule is written through the terminal, where the plan cap and the re-arm rule live.

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.