Oden Technologies Intervals API
The Intervals API from Oden Technologies — 10 operation(s) for intervals.
The Intervals API from Oden Technologies — 10 operation(s) for intervals.
openapi: 3.0.0
info:
version: 2.0.0
title: Oden Dashboards Intervals API
contact:
name: Oden Support
email: support@oden.io
url: https://oden.io/contact/
description: "The Oden Private Partner API exposes RESTful API endpoints for clients to get, create and update data on the Oden Platform.\n\nThe API is based on the OpenAPI 3.0 specification.\n### Current Version\nThe URL, and host, for the current version is [https://api.oden.app/v2](https://api.oden.app/v2).\n\n### Oden's Data Model\n- **Organization**: This represents the Organization registered as an Oden customer. An organization has an associated collection of users, factories, lines, etc. This is the entity a specific authentication token is associated with.\n- **Asset** or **Machinegroup**: Assets, or machinegroups, are collections of machines, which may either be a **Factory** or a **Line**:\n - **Factory**: Factories are collections of lines, representing a particular manufacturing location.\n - **Line**: Lines are collections of machines, often representing a particular production line. Lines may also have **Products** mapped to them, indicating what is currently being manufactured by the specific line.\n - **Machine**: Machines are the physical machines that make up a line\n- **Product**: Products capture what entities a manufacturer produces\n- **Interval**: An interval is a period of time that takes place on a manufacturing line and expresses some business concern. It's Oden's way of making metrics aggregatable, traceable, and relatable to a manufacturer.\n - **Run**: A run is a production interval that labels a period of production as being work on some single product\n - **Batch**: A batch is a production interval that represents a portion of a particular run\n - **State**: A state is an interval that tracks the availability or utilization of a line\n - **State Category**: A state category describes what state a line is in - such as ex. uptime, downtime, scrapping, etc.\n - **State Reason**: A state reason describes why a line is in a particular state - such as \"maintenance\" being a reason for the category \"downtime\".\n - **Custom**: A custom interval can track any other type of interval-based data a manufacturer might want to analyze. These are created on a per-factory basis.\n- **Target**: Targets specify values and upper/lower thresholds for metrics when specific products are running on specific lines\n- **Scrap/Yield**: Scrap/yield output specifies amount of produced product on a line during either a run or batch interval. Oden will categorize all output as either scrap or yield - as specified by the Scrap Yield Schema for a given factory. If you have other categories, like rework/blocked/off-grade, you must choose between categorizing those amounts as either good or bad production by specifying as scrap or yield. Clients may also add scrap codes (i.e., reasons) to a given Scrap Yield Data entry.\n - **Scrap Code**: A scrap code is a code that explains the reason for a scrap/yield raw data input - such as \"Rework\"\n- **Quality Test**: Quality Tests are results of quality assurance tests done on site, and uploaded to Oden. They may be attached to a single Batch or Run.\n- **Metric**: Known in factories as \"tags\", metrics are the raw data that is collected by Oden from the machines and devices on the factory floor.\n- **Metric Group**: Metric groups are metrics that represent the same thing across different lines. They provide common display names for tags and allow labeling groups of tags as measuring key types of data like performance or production.\n- **Maintenance Work Order**: A maintenance work order can be used to track work orders maintained in MaintainX and associate them with an Oden line. \n\n### Best Practices\nUnder the current implementation, the Oden API does not rate limit requests from clients.\n\nHowever, rate limiting will be introduced in the near future and it is recommended that users design their API\nclients to not exceed a request rate of **one per second**.\n\n### Schema\nAll v2 API access is over HTTPS and accessed from https://api.oden.app/v2\nAll data is sent and received as JSON.\n\nAPI requests with duplicate keys will process only the data for the first key detected and ignore the rest, so it's not recommended. Batching multiple messages in this way is currently not possible.\n - Example of duplicate key in JSON: {\"raw_data\":{\"scrap\":\"10\",\"scrap\":\"100\"}}\n\nAll timestamps are returned in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format:\n\n `YYYY-MM-DDTHH:MM:SSZ`\n\nAll durations are returned in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format with the largest unit of time being the hour:\n\n `PT[n]H[n]M[n]S`\n\nAll timestamps sent to the API in POST requests should be in ISO 8601 format.\n### HTTP Verbs\nThe ONLY HTTP call type (sometimes called *verb* or *method*) used within Oden's API is **POST**.\nThere are three actions supported via a **POST**; call, search, set, and delete, together supporting CRUD operations;\n - **search** requests are used to search for and *read* objects in the Oden Platform\n - All Oden Objects may be uniquely identified by some combination of, or a single, parameter.\n - Ex a `line` my be identified by either:\n - `id`\n - `name` AND `factory`\n - **set** requests are used to *create* or *update* objects\n - **delete** requests are used to *delete* objects. If a delete endpoint is not yet implemented for a given object, users may choose to update the values of a specific entity to null or 0 values.\n\n### URI Components\nAll endpoints may be accessed with the URI pattern:\n`https://api.oden.app/v2/{object}/{action}`\n\nWhere:\n - `object` is the name of the object being requested:\n - `factory`, `quality_test`, `interval`, `line`, etc...\n - `action` is the name of the action being requested\n - `search` , `set` , `delete`\n\ne.g. `https://api.oden.app/v2/factory/search`\n\n# Authentication\nClients can authenticate through the v2 API using a Token provided by Oden. Tokens are opaque strings similar to\n[Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) tokens that the client must\npass in the [HTTP Authorization request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) in every request.\nThe syntax is as follows:\n\n`Authorization: <type> <credentials>`\n\nWhere \\<type\\> is \"Token\" and \\<credentials\\> is the Token string. For example:\n\n`Authorization: Token tokenStringProvidedByOden`\n\nAuthenticating with an invalid Token will return `401 Unauthorized Error`.\n\nAuthenticating with a Token that is not authorized to read requested data will return `403 Forbidden Error`.\n\nSome endpoints may require requests to be broken out by machinegroup (i.e., line or factory) and the number of\nrequests would scale accordingly. This multiplicity should be taken into consideration when deciding on the\nfrequency the API client makes requests to the Oden endpoints.\n\nTo authenticate in this [UI](https://api.oden.app/v2/ui/), click the Lock icon, and copy/paste the token into the Authorize box.\n"
servers:
- url: https://api.oden.app
description: Oden API server
security:
- APIKeyAuth: []
tags:
- name: Intervals
paths:
/v2/interval/search:
post:
operationId: search_intervals
summary: Search intervals on a line
tags:
- Intervals
description: 'Searches for intervals by `type`, `line` and other optional parameters:
- `id` (for a specific Interval)
- `match: unique` or omit
OR
- `match : last` for the most recent Interval of the given type on the given line
OR
- `start_time` and `end_time` (for a range of Intervals over a period of time)
- `match: all` for more than one result
OR
- match all intervals for all lines in a given factory
AND/OR
- `name` (only for Intervals with a matching name)
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Interval'
examples:
Search for states on a line over a time period:
summary: Search for states on a line over a time period
value:
type:
name: STATE
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
start_time: '2021-04-04T08:00:04Z'
end_time: '2021-04-10T08:00:04Z'
match: all
Search for an custom interval type interval:
summary: Search for an operator id type interval
value:
id: 1809d88adf0
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
type:
name: operator id
Search for states on all lines in a given factory:
summary: Search for states on all lines in a given factory
value:
type:
name: STATE
line:
factory:
name: Factory A
match: all
start_time: '2021-04-04T08:00:04Z'
end_time: '2021-04-10T08:00:04Z'
match: all
responses:
'200':
description: A list of intervals.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Interval'
'409':
$ref: '#/components/responses/NotUniqueError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
'400':
$ref: '#/components/responses/ParameterError'
'404':
$ref: '#/components/responses/NotFoundError'
/v2/interval/set:
post:
operationId: set_interval
summary: Create or update an interval
tags:
- Intervals
description: "Create or update an Interval.\n\nMust include `line` and `type`. `match` must be omitted, `unique` or `last`\n\n - If `id` is not supplied, a new Interval will be created.\n\n - If `id` is supplied, existing Interval will be updated. This interval's start time can be modified using `start_time` field.\n\nTo update a specific interval supply the `id` of that interval.\n\nIf the interval exists with all the same parameters nothing is done.\n\nTo update the most recent Interval of a given `type` on a `line` one may use `match: last` and omit `id`\n\nFor `RUN` type: if `product` and/or `product_mapping` does not exist a new one will be created. Further a `target`\nmay be set by adding a `target` to the metadata field. The `line` and `product` for this target will be the same as the interval.\n\nPlease see examples for more specific information.\n"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Interval'
examples:
Create a Run, full schema:
summary: Create a Run
value:
type:
name: RUN
name: example_run
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: Line 01
factory:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: Factory A
start_time: '2021-04-04T08:00:04Z'
metadata:
product:
name: Example Product
Create a Run, full schema, with target:
summary: Create a Run with a target
value:
type:
name: RUN
name: example_run
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: Line 01
factory:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: Factory A
start_time: '2021-04-04T08:00:04Z'
metadata:
product:
name: Example Product
target:
lsl: 1
target_value: 2
usl: 3
metric_group:
name: metric group name
Create a Run, UUIDs only:
summary: Create a Run - uuids only
value:
type:
name: RUN
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
metadata:
product:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
start_time: '2021-04-04T08:00:04Z'
Create a Run, names only:
summary: Create a Run - names only
value:
type:
name: RUN
line:
name: Line 01
factory:
name: Factory A
metadata:
product:
name: Example Product
start_time: '2021-04-04T08:00:04Z'
Create a Batch:
summary: Create a Batch
value:
type:
name: BATCH
name: example_batch
line:
name: Line 01
factory:
name: Factory A
start_time: '2021-04-04T08:00:04Z'
Update a custom interval type interval:
summary: Update an operator id type interval
value:
id: 1809d88adf0
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: updated_operator_id
type:
name: operator id
Create a Run with a corresponding deletion example:
summary: Create a Run with a corresponding deletion example
value:
type:
name: RUN
name: deletable_run
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
start_time: '2021-04-04T08:00:04Z'
metadata:
product:
name: Example Product
Create a State with a corresponding deletion example:
summary: Create a State with a corresponding delete example
value:
type:
name: STATE
name: deletable_state
line:
id: 4787d6fb-f01e-405b-a38d-db23e32fa0d1
start_time: '2021-04-04T08:00:04Z'
metadata:
category:
name: Planned Downtime
reason:
name: Preventive Maintenance
Create a Batch with a corresponding deletion example:
summary: Create a Batch with a corresponding deletion example
value:
type:
name: BATCH
name: deletable_batch
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
start_time: '2021-04-04T08:00:04Z'
responses:
'200':
description: Updated interval.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Interval'
examples:
Set interval:
value:
- type:
id: 6f996655-4a3e-4b55-8121-724a4d14ca08
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: example_interval
start_time: 2022-06-01 08:20:04+00:00
'409':
$ref: '#/components/responses/NotUniqueError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
'400':
$ref: '#/components/responses/ParameterError'
/v2/interval/update:
post:
operationId: update_interval
summary: Update an interval
tags:
- Intervals
description: 'Update an existing Interval. This endpoint only updates intervals and will not create new ones.
Must include `line`, `type`, and `id`. The `id` must reference an existing interval.
This interval''s properties can be modified using the following fields:
- `name`: Update the interval name
- `start_time`: Modify the start time
- `end_time`: Modify the end time
- `metadata`: Update metadata (product, target, category, reason, etc.)
If the interval does not exist, a 404 error will be returned.
**Note:** The `id` must be obtained from either:
- The response when creating an interval via `/v2/interval/set`
- Searching for intervals via `/v2/interval/search`
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Interval'
examples:
Update a Run interval's product:
summary: Update a Run interval with a new product
value:
id: 178b9a1ec20
type:
name: RUN
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
metadata:
product:
name: Updated Product
Update a Run interval with target:
summary: Update a Run interval with a new target
value:
id: 178b9a1ec20
type:
name: RUN
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
metadata:
product:
name: Example Product
target:
lsl: 1
target_value: 2
usl: 3
metric_group:
name: metric group name
Update a custom interval:
summary: Update a custom interval type's name and time
value:
id: 1809d88adf0
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: updated_operator_id
type:
name: operator id
start_time: '2021-04-04T09:00:04Z'
Update a State interval:
summary: Update a State interval's category and reason
value:
id: 178a61c0f00
type:
name: STATE
line:
id: 4787d6fb-f01e-405b-a38d-db23e32fa0d1
metadata:
category:
name: Unplanned Downtime
reason:
name: Equipment Failure
Update a Batch interval:
summary: Update a Batch interval's name
value:
id: 178b9a1ec20
type:
name: BATCH
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
name: updated_batch_name
responses:
'200':
description: Updated interval.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Interval'
'400':
$ref: '#/components/responses/ParameterError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/NotUniqueError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
/v2/interval/delete:
post:
operationId: delete_interval
summary: Delete an interval
tags:
- Intervals
description: 'Delete an interval by `type`, `line`, and `id`
**Note:** The `id` must be obtained from either:
- The response when creating an interval via `/v2/interval/set`
- Searching for intervals via `/v2/interval/search`
The examples below use placeholder IDs - replace with actual IDs from your system.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Interval'
examples:
Delete a Run interval by ID:
summary: Delete a Run interval by ID (replace with actual ID)
value:
id: <REPLACE_WITH_ACTUAL_RUN_UUID>
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
type:
name: RUN
Delete a State interval by ID:
summary: Delete a State type interval by ID (replace with actual ID)
value:
id: <REPLACE_WITH_ACTUAL_STATE_ID>
line:
id: 4787d6fb-f01e-405b-a38d-db23e32fa0d1
type:
name: STATE
Delete a Batch interval by ID:
summary: Delete a Batch type interval by ID (replace with actual ID)
value:
id: <REPLACE_WITH_ACTUAL_BATCH_UUID>
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
type:
name: BATCH
Delete a custom interval:
summary: Delete an "operator id" type interval
value:
id: 1809d88adf0
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
type:
name: operator id
responses:
'200':
description: A list containing the deleted interval.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Interval'
'409':
$ref: '#/components/responses/NotUniqueError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
'400':
$ref: '#/components/responses/ParameterError'
'404':
$ref: '#/components/responses/NotFoundError'
/v2/intervals/set:
post:
operationId: bulk_set_intervals
summary: Create a set of intervals
tags:
- Intervals
description: 'Create (Does not update) a group of custom intervals, for the same `type` and `line`.
Line and type do not need to be included in each individual interval, just once at the top level.
Limitations:
- Cannot excees 2500 intervals per request.
- Will not write over other intervals
- Does not support "batch", "run", or "state" interval types.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntervalBulkCreate'
examples:
Create a set of intervals:
summary: Create a set of intervals
value:
type:
name: operator id
line:
name: Line 01
factory:
name: Factory A
intervals:
- start_time: '2021-04-04T08:00:04Z'
end_time: '2021-04-04T08:30:04Z'
name: Example Value
- start_time: '2021-04-04T09:00:04Z'
end_time: '2021-04-04T09:30:04Z'
name: Example Value 2
responses:
'200':
description: A list of created interval IDs.
content:
application/json:
schema:
type: array
items:
type: string
'400':
$ref: '#/components/responses/ParameterError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/NotUniqueError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
/v2/intervals/update:
post:
operationId: bulk_update_intervals
summary: Update a set of intervals
tags:
- Intervals
description: 'Update multiple existing intervals. This endpoint only updates intervals and will not create new ones.
Each interval in the `intervals` array must include an `id` that references an existing interval.
Updatable fields for each interval:
- `name`: Update the interval name
- `start_time`: Modify the start time
- `end_time`: Modify the end time
- `metadata`: Update metadata (product, target, category, reason, etc.)
The endpoint will attempt to update all intervals and return information about successes and failures:
- Successfully updated intervals are returned in the response
- Failed intervals are listed with their IDs and error reasons
Limitations:
- Cannot exceed 2500 intervals per request
- All intervals must be of the same `type` and on the same `line`
**Note:** Interval IDs must be obtained from either:
- The response when creating intervals via `/v2/interval/set` or `/v2/intervals/set`
- Searching for intervals via `/v2/interval/search`
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntervalBulkUpdate'
examples:
Update multiple custom intervals:
summary: Update a set of custom intervals
value:
type:
name: operator id
line:
id: 2fc8b5e5-fb88-48a7-9c35-4a763206608c
intervals:
- id: 1809d88adf0
name: updated_operator_1
start_time: '2021-04-04T08:00:04Z'
end_time: '2021-04-04T08:30:04Z'
- id: 1809d88adf1
name: updated_operator_2
start_time: '2021-04-04T09:00:04Z'
end_time: '2021-04-04T09:30:04Z'
Update multiple State intervals:
summary: Update multiple State intervals with new categories
value:
type:
name: STATE
line:
name: Line 01
factory:
name: Factory A
intervals:
- id: 178a61c0f00
metadata:
category:
name: Unplanned Downtime
reason:
name: Equipment Failure
- id: 178a61c0f01
metadata:
category:
name: Planned Downtime
reason:
name: Preventive Maintenance
responses:
'200':
description: Response containing successfully updated intervals and any failures that occurred.
content:
application/json:
schema:
type: object
properties:
num_updated:
type: integer
updated_intervals:
type: array
items:
$ref: '#/components/schemas/Interval'
num_failed:
type: integer
failed_intervals:
type: array
items:
type: object
properties:
id:
type: string
error:
type: string
'400':
$ref: '#/components/responses/ParameterError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'409':
$ref: '#/components/responses/NotUniqueError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
/v2/intervals/delete:
post:
operationId: bulk_delete_intervals
summary: Delete intervals in a time range
tags:
- Intervals
description: 'Delete a group of intervals by a single `type` and a single `line`, between `start_time` and `end_time`. Returns a list of intervals that were not deleted, and the number of intervals deleted.
Limitations:
- Cannot exceed 15,000 intervals per request, or 30 days worth of data.
- Currently does not support "batch" or "run" interval types.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntervalBulkDelete'
examples:
Delete a set of intervals:
summary: Delete a set of intervals in range
value:
line:
name: Line 01
factory:
name: Factory A
type:
name: operator id
start_time: '2021-04-04T08:00:04Z'
end_time: '2021-04-10T08:00:04Z'
responses:
'200':
description: A list containing any intervals found but not deleted.
content:
application/json:
schema:
type: object
properties:
num_deleted:
type: integer
failed_intervals:
type: array
items:
type: string
'400':
$ref: '#/components/responses/ParameterError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/NotUniqueError'
'500':
$ref: '#/components/responses/InternalError'
'501':
$ref: '#/components/responses/UnimplementedError'
/v2/interval_type/search:
post:
operationId: search_interval_types
summary: Search interval types
tags:
- Intervals
description: 'Search for Interval Types by `name`, `id`, or just `match: all` to return all Interval Types associated with the your organization.
Basic Interval Types -- `RUN`, `BATCH`, and `STATE` -- are dedicated interval types that come out-of-the-box with Oden.
Custom Interv
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oden-technologies/refs/heads/main/openapi/oden-technologies-intervals-api-openapi.yml