fxapis-com Workspace API

openapi: 3.2.0
info:
  title: fxapis Workspace API
  version: 0.1.0
  description: 'fxapis is the MetaTrader 5 API. Connect an MT5 account once, then trade it, read its positions

    and its history over plain HTTP. Choose whether each account stays connected or comes online

    only when you need it.


    ### Conventions


    - Every successful response is `{ "data": … }`; every failure is `{ "error": { "code", "message" } }`.

    Match on `code`, which is stable. `message` is written for a human and may change.

    - Every response carries `requestId`. Quote it in a support request and the entire call can be found.

    - Times are RFC 3339 in UTC. Money and prices are never floats in a request body.


    ### Bringing an account online is not instant


    A broker login takes as long as the broker takes — usually seconds, occasionally much longer.

    `POST /accounts/{id}/warm` brings an account online and returns **202** with a `pollUrl` rather than

    holding the request open, so your client''s timeout never becomes a question about someone else''s

    network. Poll `GET /accounts/{id}/status` until `state` is `ready`.


    ### Credentials


    The MT5 password you send is encrypted before it is stored, with a data key that is bound to that

    one account, and is never returned by any endpoint, written to the account record or included in

    a log line. We cannot show it back to you — if it is lost, it is reset at the broker.'
servers:
- url: https://api.fxapis.com
  description: Production
security:
- apiKey: []
tags:
- name: Workspace
  description: 'The workspace a credential belongs to: its plan, and whether trading is switched off.'
paths:
  /v1/workspace:
    get:
      summary: The workspace this credential belongs to
      tags:
      - Workspace
      description: Its plan, and whether trading is switched off. Our staff switch trading off for a whole workspace only during an incident; this is where to see it.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - id
                    - name
                    - plan
                    - planName
                    - planAssigned
                    - tradingDisabled
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      plan:
                        type: string
                        description: 'The plan in force. `none` when the workspace pays for nothing and no free plan is offered: choose a plan to connect accounts and open trades.'
                      planName:
                        type: string
                      planAssigned:
                        type: boolean
                        description: The plan was arranged with us rather than paid for, and is changed by talking to us.
                      tradingDisabled:
                        type: boolean
                        description: Trading is switched off for the whole workspace. While it is, every order is refused with `409 TRADING_DISABLED` — closes included.
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable, machine-readable. Match on this, not on the message.
                      message:
                        type: string
                        description: For a human. May change between releases.
                      details:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
                    required:
                    - code
                    - message
                  requestId:
                    type: string
                    description: Also on every response. Quote it in a support request and the whole call can be found.
      operationId: getV1Workspace
      x-operation-id-source: derived
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer fx_live_<id>_<secret>`.


        A key is shown once, at creation. We cannot show it again or recover it for you.

        Keys carry a label (`live` or `test`) in the key itself, so each configuration is easy to tell

        apart. Both reach real brokers: test with a broker demo account.


        Scopes are per key. A key without `accounts:write` can read accounts and nothing else.'
    adminKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer fx_admin_<id>_<secret>`.


        An admin key manages this workspace''s ordinary API keys (`/v1/api-keys`) and can do nothing else.

        Only the workspace owner makes one, in the console, optionally limited to IP addresses and given

        an expiry. Every request made with one is audited.'